Upgrade to ExtJS 3.1.0 - Released 12/16/2009
[extjs.git] / docs / source / Element.alignment.html
index 585fa48..0f5cd89 100644 (file)
-<html>
-<head>
-  <title>The source code</title>
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
-</head>
-<body  onload="prettyPrint();">
-    <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.0.3
- * Copyright(c) 2006-2009 Ext JS, LLC
- * licensing@extjs.com
- * http://www.extjs.com/license
+<html>\r
+<head>\r
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
+  <title>The source code</title>\r
+    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
+    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
+</head>\r
+<body  onload="prettyPrint();">\r
+    <pre class="prettyprint lang-js">/**
+ * @class Ext.Element
  */
-/**\r
- * @class Ext.Element\r
- */\r
-Ext.Element.addMethods({\r
-    <div id="method-Ext.Element-getAnchorXY"></div>/**\r
-     * Gets the x,y coordinates specified by the anchor position on the element.\r
-     * @param {String} anchor (optional) The specified anchor position (defaults to "c").  See {@link #alignTo}\r
-     * for details on supported anchor positions.\r
-     * @param {Boolean} local (optional) True to get the local (element top/left-relative) anchor position instead\r
-     * of page coordinates\r
-     * @param {Object} size (optional) An object containing the size to use for calculating anchor position\r
-     * {width: (target width), height: (target height)} (defaults to the element's current size)\r
-     * @return {Array} [x, y] An array containing the element's x and y coordinates\r
-     */\r
-    getAnchorXY : function(anchor, local, s){\r
-        //Passing a different size is useful for pre-calculating anchors,\r
-        //especially for anchored animations that change the el size.\r
-               anchor = (anchor || "tl").toLowerCase();\r
-        s = s || {};\r
-        \r
-        var me = this,        \r
-               vp = me.dom == document.body || me.dom == document,\r
-               w = s.width || vp ? Ext.lib.Dom.getViewWidth() : me.getWidth(),\r
-               h = s.height || vp ? Ext.lib.Dom.getViewHeight() : me.getHeight(),                              \r
-               xy,             \r
-               r = Math.round,\r
-               o = me.getXY(),\r
-               scroll = me.getScroll(),\r
-               extraX = vp ? scroll.left : !local ? o[0] : 0,\r
-               extraY = vp ? scroll.top : !local ? o[1] : 0,\r
-               hash = {\r
-                       c  : [r(w * 0.5), r(h * 0.5)],\r
-                       t  : [r(w * 0.5), 0],\r
-                       l  : [0, r(h * 0.5)],\r
-                       r  : [w, r(h * 0.5)],\r
-                       b  : [r(w * 0.5), h],\r
-                       tl : [0, 0],    \r
-                       bl : [0, h],\r
-                       br : [w, h],\r
-                       tr : [w, 0]\r
-               };\r
-        \r
-        xy = hash[anchor];     \r
-        return [xy[0] + extraX, xy[1] + extraY]; \r
-    },\r
-\r
-    <div id="method-Ext.Element-anchorTo"></div>/**\r
-     * Anchors an element to another element and realigns it when the window is resized.\r
-     * @param {Mixed} element The element to align to.\r
-     * @param {String} position The position to align to.\r
-     * @param {Array} offsets (optional) Offset the positioning by [x, y]\r
-     * @param {Boolean/Object} animate (optional) True for the default animation or a standard Element animation config object\r
-     * @param {Boolean/Number} monitorScroll (optional) True to monitor body scroll and reposition. If this parameter\r
-     * is a number, it is used as the buffer delay (defaults to 50ms).\r
-     * @param {Function} callback The function to call after the animation finishes\r
-     * @return {Ext.Element} this\r
-     */\r
-    anchorTo : function(el, alignment, offsets, animate, monitorScroll, callback){        \r
-           var me = this,\r
-            dom = me.dom;\r
-           \r
-           function action(){\r
-            Ext.fly(dom).alignTo(el, alignment, offsets, animate);\r
-            Ext.callback(callback, Ext.fly(dom));\r
-        }\r
-        \r
-        Ext.EventManager.onWindowResize(action, me);\r
-        \r
-        if(!Ext.isEmpty(monitorScroll)){\r
-            Ext.EventManager.on(window, 'scroll', action, me,\r
-                {buffer: !isNaN(monitorScroll) ? monitorScroll : 50});\r
-        }\r
-        action.call(me); // align immediately\r
-        return me;\r
-    },\r
-\r
-    <div id="method-Ext.Element-getAlignToXY"></div>/**\r
-     * Gets the x,y coordinates to align this element with another element. See {@link #alignTo} for more info on the\r
-     * supported position values.\r
-     * @param {Mixed} element The element to align to.\r
-     * @param {String} position The position to align to.\r
-     * @param {Array} offsets (optional) Offset the positioning by [x, y]\r
-     * @return {Array} [x, y]\r
-     */\r
-    getAlignToXY : function(el, p, o){     \r
-        el = Ext.get(el);\r
-        \r
-        if(!el || !el.dom){\r
-            throw "Element.alignToXY with an element that doesn't exist";\r
-        }\r
-        \r
-        o = o || [0,0];\r
-        p = (p == "?" ? "tl-bl?" : (!/-/.test(p) && p !== "" ? "tl-" + p : p || "tl-bl")).toLowerCase();       \r
-                \r
-        var me = this,\r
-               d = me.dom,\r
-               a1,\r
-               a2,\r
-               x,\r
-               y,\r
-               //constrain the aligned el to viewport if necessary\r
-               w,\r
-               h,\r
-               r,\r
-               dw = Ext.lib.Dom.getViewWidth() -10, // 10px of margin for ie\r
-               dh = Ext.lib.Dom.getViewHeight()-10, // 10px of margin for ie\r
-               p1y,\r
-               p1x,            \r
-               p2y,\r
-               p2x,\r
-               swapY,\r
-               swapX,\r
-               doc = document,\r
-               docElement = doc.documentElement,\r
-               docBody = doc.body,\r
-               scrollX = (docElement.scrollLeft || docBody.scrollLeft || 0)+5,\r
-               scrollY = (docElement.scrollTop || docBody.scrollTop || 0)+5,\r
-               c = false, //constrain to viewport\r
-               p1 = "", \r
-               p2 = "",\r
-               m = p.match(/^([a-z]+)-([a-z]+)(\?)?$/);\r
-        \r
-        if(!m){\r
-           throw "Element.alignTo with an invalid alignment " + p;\r
-        }\r
-        \r
-        p1 = m[1]; \r
-        p2 = m[2]; \r
-        c = !!m[3];\r
-\r
-        //Subtract the aligned el's internal xy from the target's offset xy\r
-        //plus custom offset to get the aligned el's new offset xy\r
-        a1 = me.getAnchorXY(p1, true);\r
-        a2 = el.getAnchorXY(p2, false);\r
-\r
-        x = a2[0] - a1[0] + o[0];\r
-        y = a2[1] - a1[1] + o[1];\r
-\r
-        if(c){    \r
-              w = me.getWidth();\r
-           h = me.getHeight();\r
-           r = el.getRegion();       \r
-           //If we are at a viewport boundary and the aligned el is anchored on a target border that is\r
-           //perpendicular to the vp border, allow the aligned el to slide on that border,\r
-           //otherwise swap the aligned el to the opposite border of the target.\r
-           p1y = p1.charAt(0);\r
-           p1x = p1.charAt(p1.length-1);\r
-           p2y = p2.charAt(0);\r
-           p2x = p2.charAt(p2.length-1);\r
-           swapY = ((p1y=="t" && p2y=="b") || (p1y=="b" && p2y=="t"));\r
-           swapX = ((p1x=="r" && p2x=="l") || (p1x=="l" && p2x=="r"));          \r
-           \r
-\r
-           if (x + w > dw + scrollX) {\r
-                x = swapX ? r.left-w : dw+scrollX-w;\r
-           }\r
-           if (x < scrollX) {\r
-               x = swapX ? r.right : scrollX;\r
-           }\r
-           if (y + h > dh + scrollY) {\r
-                y = swapY ? r.top-h : dh+scrollY-h;\r
-            }\r
-           if (y < scrollY){\r
-               y = swapY ? r.bottom : scrollY;\r
-           }\r
-        }\r
-        return [x,y];\r
-    },\r
-\r
-    <div id="method-Ext.Element-alignTo"></div>/**\r
-     * Aligns this element with another element relative to the specified anchor points. If the other element is the\r
-     * document it aligns it to the viewport.\r
-     * The position parameter is optional, and can be specified in any one of the following formats:\r
-     * <ul>\r
-     *   <li><b>Blank</b>: Defaults to aligning the element's top-left corner to the target's bottom-left corner ("tl-bl").</li>\r
-     *   <li><b>One anchor (deprecated)</b>: The passed anchor position is used as the target element's anchor point.\r
-     *       The element being aligned will position its top-left corner (tl) to that point.  <i>This method has been\r
-     *       deprecated in favor of the newer two anchor syntax below</i>.</li>\r
-     *   <li><b>Two anchors</b>: If two values from the table below are passed separated by a dash, the first value is used as the\r
-     *       element's anchor point, and the second value is used as the target's anchor point.</li>\r
-     * </ul>\r
-     * In addition to the anchor points, the position parameter also supports the "?" character.  If "?" is passed at the end of\r
-     * the position string, the element will attempt to align as specified, but the position will be adjusted to constrain to\r
-     * the viewport if necessary.  Note that the element being aligned might be swapped to align to a different position than\r
-     * that specified in order to enforce the viewport constraints.\r
-     * Following are all of the supported anchor positions:\r
-<pre>\r
-Value  Description\r
------  -----------------------------\r
-tl     The top left corner (default)\r
-t      The center of the top edge\r
-tr     The top right corner\r
-l      The center of the left edge\r
-c      In the center of the element\r
-r      The center of the right edge\r
-bl     The bottom left corner\r
-b      The center of the bottom edge\r
-br     The bottom right corner\r
-</pre>\r
-Example Usage:\r
-<pre><code>\r
-// align el to other-el using the default positioning ("tl-bl", non-constrained)\r
-el.alignTo("other-el");\r
-\r
-// align the top left corner of el with the top right corner of other-el (constrained to viewport)\r
-el.alignTo("other-el", "tr?");\r
-\r
-// align the bottom right corner of el with the center left edge of other-el\r
-el.alignTo("other-el", "br-l?");\r
-\r
-// align the center of el with the bottom left corner of other-el and\r
-// adjust the x position by -6 pixels (and the y position by 0)\r
-el.alignTo("other-el", "c-bl", [-6, 0]);\r
-</code></pre>\r
-     * @param {Mixed} element The element to align to.\r
-     * @param {String} position The position to align to.\r
-     * @param {Array} offsets (optional) Offset the positioning by [x, y]\r
-     * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object\r
-     * @return {Ext.Element} this\r
-     */\r
-    alignTo : function(element, position, offsets, animate){\r
-           var me = this;\r
-        return me.setXY(me.getAlignToXY(element, position, offsets),\r
-                               me.preanim && !!animate ? me.preanim(arguments, 3) : false);\r
-    },\r
-    \r
-    // private ==>  used outside of core\r
-    adjustForConstraints : function(xy, parent, offsets){\r
-        return this.getConstrainToXY(parent || document, false, offsets, xy) ||  xy;\r
-    },\r
-\r
-    // private ==>  used outside of core\r
-    getConstrainToXY : function(el, local, offsets, proposedXY){   \r
-           var os = {top:0, left:0, bottom:0, right: 0};\r
-\r
-        return function(el, local, offsets, proposedXY){\r
-            el = Ext.get(el);\r
-            offsets = offsets ? Ext.applyIf(offsets, os) : os;\r
-\r
-            var vw, vh, vx = 0, vy = 0;\r
-            if(el.dom == document.body || el.dom == document){\r
-                vw =Ext.lib.Dom.getViewWidth();\r
-                vh = Ext.lib.Dom.getViewHeight();\r
-            }else{\r
-                vw = el.dom.clientWidth;\r
-                vh = el.dom.clientHeight;\r
-                if(!local){\r
-                    var vxy = el.getXY();\r
-                    vx = vxy[0];\r
-                    vy = vxy[1];\r
-                }\r
-            }\r
-\r
-            var s = el.getScroll();\r
-\r
-            vx += offsets.left + s.left;\r
-            vy += offsets.top + s.top;\r
-\r
-            vw -= offsets.right;\r
-            vh -= offsets.bottom;\r
-\r
-            var vr = vx+vw;\r
-            var vb = vy+vh;\r
-\r
-            var xy = proposedXY || (!local ? this.getXY() : [this.getLeft(true), this.getTop(true)]);\r
-            var x = xy[0], y = xy[1];\r
-            var w = this.dom.offsetWidth, h = this.dom.offsetHeight;\r
-\r
-            // only move it if it needs it\r
-            var moved = false;\r
-\r
-            // first validate right/bottom\r
-            if((x + w) > vr){\r
-                x = vr - w;\r
-                moved = true;\r
-            }\r
-            if((y + h) > vb){\r
-                y = vb - h;\r
-                moved = true;\r
-            }\r
-            // then make sure top/left isn't negative\r
-            if(x < vx){\r
-                x = vx;\r
-                moved = true;\r
-            }\r
-            if(y < vy){\r
-                y = vy;\r
-                moved = true;\r
-            }\r
-            return moved ? [x, y] : false;\r
-        };\r
-    }(),\r
-           \r
-           \r
-               \r
-//         el = Ext.get(el);\r
-//         offsets = Ext.applyIf(offsets || {}, {top : 0, left : 0, bottom : 0, right : 0});\r
-\r
-//         var me = this,\r
-//             doc = document,\r
-//             s = el.getScroll(),\r
-//             vxy = el.getXY(),\r
-//             vx = offsets.left + s.left, \r
-//             vy = offsets.top + s.top,               \r
-//             vw = -offsets.right, \r
-//             vh = -offsets.bottom, \r
-//             vr,\r
-//             vb,\r
-//             xy = proposedXY || (!local ? me.getXY() : [me.getLeft(true), me.getTop(true)]),\r
-//             x = xy[0],\r
-//             y = xy[1],\r
-//             w = me.dom.offsetWidth, h = me.dom.offsetHeight,\r
-//             moved = false; // only move it if it needs it\r
-//       \r
-//             \r
-//         if(el.dom == doc.body || el.dom == doc){\r
-//             vw += Ext.lib.Dom.getViewWidth();\r
-//             vh += Ext.lib.Dom.getViewHeight();\r
-//         }else{\r
-//             vw += el.dom.clientWidth;\r
-//             vh += el.dom.clientHeight;\r
-//             if(!local){                    \r
-//                 vx += vxy[0];\r
-//                 vy += vxy[1];\r
-//             }\r
-//         }\r
-\r
-//         // first validate right/bottom\r
-//         if(x + w > vx + vw){\r
-//             x = vx + vw - w;\r
-//             moved = true;\r
-//         }\r
-//         if(y + h > vy + vh){\r
-//             y = vy + vh - h;\r
-//             moved = true;\r
-//         }\r
-//         // then make sure top/left isn't negative\r
-//         if(x < vx){\r
-//             x = vx;\r
-//             moved = true;\r
-//         }\r
-//         if(y < vy){\r
-//             y = vy;\r
-//             moved = true;\r
-//         }\r
-//         return moved ? [x, y] : false;\r
-//    },\r
-    \r
-    <div id="method-Ext.Element-getCenterXY"></div>/**\r
-    * Calculates the x, y to center this element on the screen\r
-    * @return {Array} The x, y values [x, y]\r
-    */\r
-    getCenterXY : function(){\r
-        return this.getAlignToXY(document, 'c-c');\r
-    },\r
-\r
-    <div id="method-Ext.Element-center"></div>/**\r
-    * Centers the Element in either the viewport, or another Element.\r
-    * @param {Mixed} centerIn (optional) The element in which to center the element.\r
-    */\r
-    center : function(centerIn){\r
-        return this.alignTo(centerIn || document, 'c-c');        \r
-    }    \r
-});\r
+Ext.Element.addMethods({
+    <div id="method-Ext.Element-getAnchorXY"></div>/**
+     * Gets the x,y coordinates specified by the anchor position on the element.
+     * @param {String} anchor (optional) The specified anchor position (defaults to "c").  See {@link #alignTo}
+     * for details on supported anchor positions.
+     * @param {Boolean} local (optional) True to get the local (element top/left-relative) anchor position instead
+     * of page coordinates
+     * @param {Object} size (optional) An object containing the size to use for calculating anchor position
+     * {width: (target width), height: (target height)} (defaults to the element's current size)
+     * @return {Array} [x, y] An array containing the element's x and y coordinates
+     */
+    getAnchorXY : function(anchor, local, s){
+        //Passing a different size is useful for pre-calculating anchors,
+        //especially for anchored animations that change the el size.
+               anchor = (anchor || "tl").toLowerCase();
+        s = s || {};
+        
+        var me = this,        
+               vp = me.dom == document.body || me.dom == document,
+               w = s.width || vp ? Ext.lib.Dom.getViewWidth() : me.getWidth(),
+               h = s.height || vp ? Ext.lib.Dom.getViewHeight() : me.getHeight(),                              
+               xy,             
+               r = Math.round,
+               o = me.getXY(),
+               scroll = me.getScroll(),
+               extraX = vp ? scroll.left : !local ? o[0] : 0,
+               extraY = vp ? scroll.top : !local ? o[1] : 0,
+               hash = {
+                       c  : [r(w * 0.5), r(h * 0.5)],
+                       t  : [r(w * 0.5), 0],
+                       l  : [0, r(h * 0.5)],
+                       r  : [w, r(h * 0.5)],
+                       b  : [r(w * 0.5), h],
+                       tl : [0, 0],    
+                       bl : [0, h],
+                       br : [w, h],
+                       tr : [w, 0]
+               };
+        
+        xy = hash[anchor];     
+        return [xy[0] + extraX, xy[1] + extraY]; 
+    },
+
+    <div id="method-Ext.Element-anchorTo"></div>/**
+     * Anchors an element to another element and realigns it when the window is resized.
+     * @param {Mixed} element The element to align to.
+     * @param {String} position The position to align to.
+     * @param {Array} offsets (optional) Offset the positioning by [x, y]
+     * @param {Boolean/Object} animate (optional) True for the default animation or a standard Element animation config object
+     * @param {Boolean/Number} monitorScroll (optional) True to monitor body scroll and reposition. If this parameter
+     * is a number, it is used as the buffer delay (defaults to 50ms).
+     * @param {Function} callback The function to call after the animation finishes
+     * @return {Ext.Element} this
+     */
+    anchorTo : function(el, alignment, offsets, animate, monitorScroll, callback){        
+           var me = this,
+            dom = me.dom,
+            scroll = !Ext.isEmpty(monitorScroll),
+            action = function(){
+                Ext.fly(dom).alignTo(el, alignment, offsets, animate);
+                Ext.callback(callback, Ext.fly(dom));
+            },
+            anchor = this.getAnchor();
+            
+        // previous listener anchor, remove it
+        this.removeAnchor();
+        Ext.apply(anchor, {
+            fn: action,
+            scroll: scroll
+        });
+
+        Ext.EventManager.onWindowResize(action, null);
+        
+        if(scroll){
+            Ext.EventManager.on(window, 'scroll', action, null,
+                {buffer: !isNaN(monitorScroll) ? monitorScroll : 50});
+        }
+        action.call(me); // align immediately
+        return me;
+    },
+    
+    <div id="method-Ext.Element-removeAnchor"></div>/**
+     * Remove any anchor to this element. See {@link #anchorTo}.
+     * @return {Ext.Element} this
+     */
+    removeAnchor : function(){
+        var me = this,
+            anchor = this.getAnchor();
+            
+        if(anchor && anchor.fn){
+            Ext.EventManager.removeResizeListener(anchor.fn);
+            if(anchor.scroll){
+                Ext.EventManager.un(window, 'scroll', anchor.fn);
+            }
+            delete anchor.fn;
+        }
+        return me;
+    },
+    
+    // private
+    getAnchor : function(){
+        var data = Ext.Element.data,
+            dom = this.dom;
+            if (!dom) {
+                return;
+            }
+            var anchor = data(dom, '_anchor');
+            
+        if(!anchor){
+            anchor = data(dom, '_anchor', {});
+        }
+        return anchor;
+    },
+
+    <div id="method-Ext.Element-getAlignToXY"></div>/**
+     * Gets the x,y coordinates to align this element with another element. See {@link #alignTo} for more info on the
+     * supported position values.
+     * @param {Mixed} element The element to align to.
+     * @param {String} position (optional, defaults to "tl-bl?") The position to align to.
+     * @param {Array} offsets (optional) Offset the positioning by [x, y]
+     * @return {Array} [x, y]
+     */
+    getAlignToXY : function(el, p, o){     
+        el = Ext.get(el);
+        
+        if(!el || !el.dom){
+            throw "Element.alignToXY with an element that doesn't exist";
+        }
+        
+        o = o || [0,0];
+        p = (!p || p == "?" ? "tl-bl?" : (!/-/.test(p) && p !== "" ? "tl-" + p : p || "tl-bl")).toLowerCase();       
+                
+        var me = this,
+               d = me.dom,
+               a1,
+               a2,
+               x,
+               y,
+               //constrain the aligned el to viewport if necessary
+               w,
+               h,
+               r,
+               dw = Ext.lib.Dom.getViewWidth() -10, // 10px of margin for ie
+               dh = Ext.lib.Dom.getViewHeight()-10, // 10px of margin for ie
+               p1y,
+               p1x,            
+               p2y,
+               p2x,
+               swapY,
+               swapX,
+               doc = document,
+               docElement = doc.documentElement,
+               docBody = doc.body,
+               scrollX = (docElement.scrollLeft || docBody.scrollLeft || 0)+5,
+               scrollY = (docElement.scrollTop || docBody.scrollTop || 0)+5,
+               c = false, //constrain to viewport
+               p1 = "", 
+               p2 = "",
+               m = p.match(/^([a-z]+)-([a-z]+)(\?)?$/);
+        
+        if(!m){
+           throw "Element.alignTo with an invalid alignment " + p;
+        }
+        
+        p1 = m[1]; 
+        p2 = m[2]; 
+        c = !!m[3];
+
+        //Subtract the aligned el's internal xy from the target's offset xy
+        //plus custom offset to get the aligned el's new offset xy
+        a1 = me.getAnchorXY(p1, true);
+        a2 = el.getAnchorXY(p2, false);
+
+        x = a2[0] - a1[0] + o[0];
+        y = a2[1] - a1[1] + o[1];
+
+        if(c){    
+              w = me.getWidth();
+           h = me.getHeight();
+           r = el.getRegion();       
+           //If we are at a viewport boundary and the aligned el is anchored on a target border that is
+           //perpendicular to the vp border, allow the aligned el to slide on that border,
+           //otherwise swap the aligned el to the opposite border of the target.
+           p1y = p1.charAt(0);
+           p1x = p1.charAt(p1.length-1);
+           p2y = p2.charAt(0);
+           p2x = p2.charAt(p2.length-1);
+           swapY = ((p1y=="t" && p2y=="b") || (p1y=="b" && p2y=="t"));
+           swapX = ((p1x=="r" && p2x=="l") || (p1x=="l" && p2x=="r"));          
+           
+
+           if (x + w > dw + scrollX) {
+                x = swapX ? r.left-w : dw+scrollX-w;
+           }
+           if (x < scrollX) {
+               x = swapX ? r.right : scrollX;
+           }
+           if (y + h > dh + scrollY) {
+                y = swapY ? r.top-h : dh+scrollY-h;
+            }
+           if (y < scrollY){
+               y = swapY ? r.bottom : scrollY;
+           }
+        }
+        return [x,y];
+    },
+
+    <div id="method-Ext.Element-alignTo"></div>/**
+     * Aligns this element with another element relative to the specified anchor points. If the other element is the
+     * document it aligns it to the viewport.
+     * The position parameter is optional, and can be specified in any one of the following formats:
+     * <ul>
+     *   <li><b>Blank</b>: Defaults to aligning the element's top-left corner to the target's bottom-left corner ("tl-bl").</li>
+     *   <li><b>One anchor (deprecated)</b>: The passed anchor position is used as the target element's anchor point.
+     *       The element being aligned will position its top-left corner (tl) to that point.  <i>This method has been
+     *       deprecated in favor of the newer two anchor syntax below</i>.</li>
+     *   <li><b>Two anchors</b>: If two values from the table below are passed separated by a dash, the first value is used as the
+     *       element's anchor point, and the second value is used as the target's anchor point.</li>
+     * </ul>
+     * In addition to the anchor points, the position parameter also supports the "?" character.  If "?" is passed at the end of
+     * the position string, the element will attempt to align as specified, but the position will be adjusted to constrain to
+     * the viewport if necessary.  Note that the element being aligned might be swapped to align to a different position than
+     * that specified in order to enforce the viewport constraints.
+     * Following are all of the supported anchor positions:
+<pre>
+Value  Description
+-----  -----------------------------
+tl     The top left corner (default)
+t      The center of the top edge
+tr     The top right corner
+l      The center of the left edge
+c      In the center of the element
+r      The center of the right edge
+bl     The bottom left corner
+b      The center of the bottom edge
+br     The bottom right corner
 </pre>
-</body>
+Example Usage:
+<pre><code>
+// align el to other-el using the default positioning ("tl-bl", non-constrained)
+el.alignTo("other-el");
+
+// align the top left corner of el with the top right corner of other-el (constrained to viewport)
+el.alignTo("other-el", "tr?");
+
+// align the bottom right corner of el with the center left edge of other-el
+el.alignTo("other-el", "br-l?");
+
+// align the center of el with the bottom left corner of other-el and
+// adjust the x position by -6 pixels (and the y position by 0)
+el.alignTo("other-el", "c-bl", [-6, 0]);
+</code></pre>
+     * @param {Mixed} element The element to align to.
+     * @param {String} position (optional, defaults to "tl-bl?") The position to align to.
+     * @param {Array} offsets (optional) Offset the positioning by [x, y]
+     * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
+     * @return {Ext.Element} this
+     */
+    alignTo : function(element, position, offsets, animate){
+           var me = this;
+        return me.setXY(me.getAlignToXY(element, position, offsets),
+                               me.preanim && !!animate ? me.preanim(arguments, 3) : false);
+    },
+    
+    // private ==>  used outside of core
+    adjustForConstraints : function(xy, parent, offsets){
+        return this.getConstrainToXY(parent || document, false, offsets, xy) ||  xy;
+    },
+
+    // private ==>  used outside of core
+    getConstrainToXY : function(el, local, offsets, proposedXY){   
+           var os = {top:0, left:0, bottom:0, right: 0};
+
+        return function(el, local, offsets, proposedXY){
+            el = Ext.get(el);
+            offsets = offsets ? Ext.applyIf(offsets, os) : os;
+
+            var vw, vh, vx = 0, vy = 0;
+            if(el.dom == document.body || el.dom == document){
+                vw =Ext.lib.Dom.getViewWidth();
+                vh = Ext.lib.Dom.getViewHeight();
+            }else{
+                vw = el.dom.clientWidth;
+                vh = el.dom.clientHeight;
+                if(!local){
+                    var vxy = el.getXY();
+                    vx = vxy[0];
+                    vy = vxy[1];
+                }
+            }
+
+            var s = el.getScroll();
+
+            vx += offsets.left + s.left;
+            vy += offsets.top + s.top;
+
+            vw -= offsets.right;
+            vh -= offsets.bottom;
+
+            var vr = vx+vw;
+            var vb = vy+vh;
+
+            var xy = proposedXY || (!local ? this.getXY() : [this.getLeft(true), this.getTop(true)]);
+            var x = xy[0], y = xy[1];
+            var w = this.dom.offsetWidth, h = this.dom.offsetHeight;
+
+            // only move it if it needs it
+            var moved = false;
+
+            // first validate right/bottom
+            if((x + w) > vr){
+                x = vr - w;
+                moved = true;
+            }
+            if((y + h) > vb){
+                y = vb - h;
+                moved = true;
+            }
+            // then make sure top/left isn't negative
+            if(x < vx){
+                x = vx;
+                moved = true;
+            }
+            if(y < vy){
+                y = vy;
+                moved = true;
+            }
+            return moved ? [x, y] : false;
+        };
+    }(),
+           
+           
+               
+//         el = Ext.get(el);
+//         offsets = Ext.applyIf(offsets || {}, {top : 0, left : 0, bottom : 0, right : 0});
+
+//         var me = this,
+//             doc = document,
+//             s = el.getScroll(),
+//             vxy = el.getXY(),
+//             vx = offsets.left + s.left, 
+//             vy = offsets.top + s.top,               
+//             vw = -offsets.right, 
+//             vh = -offsets.bottom, 
+//             vr,
+//             vb,
+//             xy = proposedXY || (!local ? me.getXY() : [me.getLeft(true), me.getTop(true)]),
+//             x = xy[0],
+//             y = xy[1],
+//             w = me.dom.offsetWidth, h = me.dom.offsetHeight,
+//             moved = false; // only move it if it needs it
+//       
+//             
+//         if(el.dom == doc.body || el.dom == doc){
+//             vw += Ext.lib.Dom.getViewWidth();
+//             vh += Ext.lib.Dom.getViewHeight();
+//         }else{
+//             vw += el.dom.clientWidth;
+//             vh += el.dom.clientHeight;
+//             if(!local){                    
+//                 vx += vxy[0];
+//                 vy += vxy[1];
+//             }
+//         }
+
+//         // first validate right/bottom
+//         if(x + w > vx + vw){
+//             x = vx + vw - w;
+//             moved = true;
+//         }
+//         if(y + h > vy + vh){
+//             y = vy + vh - h;
+//             moved = true;
+//         }
+//         // then make sure top/left isn't negative
+//         if(x < vx){
+//             x = vx;
+//             moved = true;
+//         }
+//         if(y < vy){
+//             y = vy;
+//             moved = true;
+//         }
+//         return moved ? [x, y] : false;
+//    },
+    
+    <div id="method-Ext.Element-getCenterXY"></div>/**
+    * Calculates the x, y to center this element on the screen
+    * @return {Array} The x, y values [x, y]
+    */
+    getCenterXY : function(){
+        return this.getAlignToXY(document, 'c-c');
+    },
+
+    <div id="method-Ext.Element-center"></div>/**
+    * Centers the Element in either the viewport, or another Element.
+    * @param {Mixed} centerIn (optional) The element in which to center the element.
+    */
+    center : function(centerIn){
+        return this.alignTo(centerIn || document, 'c-c');        
+    }    
+});
+</pre>    \r
+</body>\r
 </html>
\ No newline at end of file