Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / src / core / Element.position-more.js
1 /*!
2  * Ext JS Library 3.3.1
3  * Copyright(c) 2006-2010 Sencha Inc.
4  * licensing@sencha.com
5  * http://www.sencha.com/license
6  */
7 /**
8  * @class Ext.Element
9  */
10 Ext.Element.addMethods({
11     /**
12      * 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.
13      * @param {Object} box The box to fill {x, y, width, height}
14      * @param {Boolean} adjust (optional) Whether to adjust for box-model issues automatically
15      * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
16      * @return {Ext.Element} this
17      */
18     setBox : function(box, adjust, animate){
19         var me = this,
20                 w = box.width, 
21                 h = box.height;
22         if((adjust && !me.autoBoxAdjust) && !me.isBorderBox()){
23            w -= (me.getBorderWidth("lr") + me.getPadding("lr"));
24            h -= (me.getBorderWidth("tb") + me.getPadding("tb"));
25         }
26         me.setBounds(box.x, box.y, w, h, me.animTest.call(me, arguments, animate, 2));
27         return me;
28     },
29
30     /**
31      * Return an object defining the area of this Element which can be passed to {@link #setBox} to
32      * set another Element's size/location to match this element.
33      * @param {Boolean} contentBox (optional) If true a box for the content of the element is returned.
34      * @param {Boolean} local (optional) If true the element's left and top are returned instead of page x/y.
35      * @return {Object} box An object in the format<pre><code>
36 {
37     x: &lt;Element's X position>,
38     y: &lt;Element's Y position>,
39     width: &lt;Element's width>,
40     height: &lt;Element's height>,
41     bottom: &lt;Element's lower bound>,
42     right: &lt;Element's rightmost bound>
43 }
44 </code></pre>
45      * The returned object may also be addressed as an Array where index 0 contains the X position
46      * and index 1 contains the Y position. So the result may also be used for {@link #setXY}
47      */
48         getBox : function(contentBox, local) {      
49             var me = this,
50                 xy,
51                 left,
52                 top,
53                 getBorderWidth = me.getBorderWidth,
54                 getPadding = me.getPadding, 
55                 l,
56                 r,
57                 t,
58                 b;
59         if(!local){
60             xy = me.getXY();
61         }else{
62             left = parseInt(me.getStyle("left"), 10) || 0;
63             top = parseInt(me.getStyle("top"), 10) || 0;
64             xy = [left, top];
65         }
66         var el = me.dom, w = el.offsetWidth, h = el.offsetHeight, bx;
67         if(!contentBox){
68             bx = {x: xy[0], y: xy[1], 0: xy[0], 1: xy[1], width: w, height: h};
69         }else{
70             l = getBorderWidth.call(me, "l") + getPadding.call(me, "l");
71             r = getBorderWidth.call(me, "r") + getPadding.call(me, "r");
72             t = getBorderWidth.call(me, "t") + getPadding.call(me, "t");
73             b = getBorderWidth.call(me, "b") + getPadding.call(me, "b");
74             bx = {x: xy[0]+l, y: xy[1]+t, 0: xy[0]+l, 1: xy[1]+t, width: w-(l+r), height: h-(t+b)};
75         }
76         bx.right = bx.x + bx.width;
77         bx.bottom = bx.y + bx.height;
78         return bx;
79         },
80         
81     /**
82      * Move this element relative to its current position.
83      * @param {String} direction Possible values are: "l" (or "left"), "r" (or "right"), "t" (or "top", or "up"), "b" (or "bottom", or "down").
84      * @param {Number} distance How far to move the element in pixels
85      * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
86      * @return {Ext.Element} this
87      */
88      move : function(direction, distance, animate){
89         var me = this,          
90                 xy = me.getXY(),
91                 x = xy[0],
92                 y = xy[1],              
93                 left = [x - distance, y],
94                 right = [x + distance, y],
95                 top = [x, y - distance],
96                 bottom = [x, y + distance],
97                 hash = {
98                         l :     left,
99                         left : left,
100                         r : right,
101                         right : right,
102                         t : top,
103                         top : top,
104                         up : top,
105                         b : bottom, 
106                         bottom : bottom,
107                         down : bottom                           
108                 };
109         
110             direction = direction.toLowerCase();    
111             me.moveTo(hash[direction][0], hash[direction][1], me.animTest.call(me, arguments, animate, 2));
112     },
113     
114     /**
115      * Quick set left and top adding default units
116      * @param {String} left The left CSS property value
117      * @param {String} top The top CSS property value
118      * @return {Ext.Element} this
119      */
120      setLeftTop : function(left, top){
121             var me = this,
122                 style = me.dom.style;
123         style.left = me.addUnits(left);
124         style.top = me.addUnits(top);
125         return me;
126     },
127     
128     /**
129      * Returns the region of the given element.
130      * The element must be part of the DOM tree to have a region (display:none or elements not appended return false).
131      * @return {Region} A Ext.lib.Region containing "top, left, bottom, right" member data.
132      */
133     getRegion : function(){
134         return Ext.lib.Dom.getRegion(this.dom);
135     },
136     
137     /**
138      * Sets the element's position and size in one shot. If animation is true then width, height, x and y will be animated concurrently.
139      * @param {Number} x X value for new position (coordinates are page-based)
140      * @param {Number} y Y value for new position (coordinates are page-based)
141      * @param {Mixed} width The new width. This may be one of:<div class="mdetail-params"><ul>
142      * <li>A Number specifying the new width in this Element's {@link #defaultUnit}s (by default, pixels)</li>
143      * <li>A String used to set the CSS width style. Animation may <b>not</b> be used.
144      * </ul></div>
145      * @param {Mixed} height The new height. This may be one of:<div class="mdetail-params"><ul>
146      * <li>A Number specifying the new height in this Element's {@link #defaultUnit}s (by default, pixels)</li>
147      * <li>A String used to set the CSS height style. Animation may <b>not</b> be used.</li>
148      * </ul></div>
149      * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
150      * @return {Ext.Element} this
151      */
152     setBounds : function(x, y, width, height, animate){
153             var me = this;
154         if (!animate || !me.anim) {
155             me.setSize(width, height);
156             me.setLocation(x, y);
157         } else {
158             me.anim({points: {to: [x, y]}, 
159                          width: {to: me.adjustWidth(width)}, 
160                          height: {to: me.adjustHeight(height)}},
161                      me.preanim(arguments, 4), 
162                      'motion');
163         }
164         return me;
165     },
166
167     /**
168      * Sets the element's position and size the specified region. If animation is true then width, height, x and y will be animated concurrently.
169      * @param {Ext.lib.Region} region The region to fill
170      * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
171      * @return {Ext.Element} this
172      */
173     setRegion : function(region, animate) {
174         return this.setBounds(region.left, region.top, region.right-region.left, region.bottom-region.top, this.animTest.call(this, arguments, animate, 1));
175     }
176 });