src/core/Element.alignment.js

   1 /*!
   2  * Ext JS Library 3.0.3
   3  * Copyright(c) 2006-2009 Ext JS, LLC
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**\r
   8  * @class Ext.Element\r
   9  */\r
  10 Ext.Element.addMethods({\r
  11     /**\r
  12      * Gets the x,y coordinates specified by the anchor position on the element.\r
  13      * @param {String} anchor (optional) The specified anchor position (defaults to "c").  See {@link #alignTo}\r
  14      * for details on supported anchor positions.\r
  15      * @param {Boolean} local (optional) True to get the local (element top/left-relative) anchor position instead\r
  16      * of page coordinates\r
  17      * @param {Object} size (optional) An object containing the size to use for calculating anchor position\r
  18      * {width: (target width), height: (target height)} (defaults to the element's current size)\r
  19      * @return {Array} [x, y] An array containing the element's x and y coordinates\r
  20      */\r
  21     getAnchorXY : function(anchor, local, s){\r
  22         //Passing a different size is useful for pre-calculating anchors,\r
  23         //especially for anchored animations that change the el size.\r
  24                 anchor = (anchor || "tl").toLowerCase();\r
  25         s = s || {};\r
  26         \r
  27         var me = this,        \r
  28                 vp = me.dom == document.body || me.dom == document,\r
  29                 w = s.width || vp ? Ext.lib.Dom.getViewWidth() : me.getWidth(),\r
  30                 h = s.height || vp ? Ext.lib.Dom.getViewHeight() : me.getHeight(),                              \r
  31                 xy,             \r
  32                 r = Math.round,\r
  33                 o = me.getXY(),\r
  34                 scroll = me.getScroll(),\r
  35                 extraX = vp ? scroll.left : !local ? o[0] : 0,\r
  36                 extraY = vp ? scroll.top : !local ? o[1] : 0,\r
  37                 hash = {\r
  38                         c  : [r(w * 0.5), r(h * 0.5)],\r
  39                         t  : [r(w * 0.5), 0],\r
  40                         l  : [0, r(h * 0.5)],\r
  41                         r  : [w, r(h * 0.5)],\r
  42                         b  : [r(w * 0.5), h],\r
  43                         tl : [0, 0],    \r
  44                         bl : [0, h],\r
  45                         br : [w, h],\r
  46                         tr : [w, 0]\r
  47                 };\r
  48         \r
  49         xy = hash[anchor];      \r
  50         return [xy[0] + extraX, xy[1] + extraY]; \r
  51     },\r
  52 \r
  53     /**\r
  54      * Anchors an element to another element and realigns it when the window is resized.\r
  55      * @param {Mixed} element The element to align to.\r
  56      * @param {String} position The position to align to.\r
  57      * @param {Array} offsets (optional) Offset the positioning by [x, y]\r
  58      * @param {Boolean/Object} animate (optional) True for the default animation or a standard Element animation config object\r
  59      * @param {Boolean/Number} monitorScroll (optional) True to monitor body scroll and reposition. If this parameter\r
  60      * is a number, it is used as the buffer delay (defaults to 50ms).\r
  61      * @param {Function} callback The function to call after the animation finishes\r
  62      * @return {Ext.Element} this\r
  63      */\r
  64     anchorTo : function(el, alignment, offsets, animate, monitorScroll, callback){        \r
  65             var me = this,\r
  66             dom = me.dom;\r
  67             \r
  68             function action(){\r
  69             Ext.fly(dom).alignTo(el, alignment, offsets, animate);\r
  70             Ext.callback(callback, Ext.fly(dom));\r
  71         }\r
  72         \r
  73         Ext.EventManager.onWindowResize(action, me);\r
  74         \r
  75         if(!Ext.isEmpty(monitorScroll)){\r
  76             Ext.EventManager.on(window, 'scroll', action, me,\r
  77                 {buffer: !isNaN(monitorScroll) ? monitorScroll : 50});\r
  78         }\r
  79         action.call(me); // align immediately\r
  80         return me;\r
  81     },\r
  82 \r
  83     /**\r
  84      * Gets the x,y coordinates to align this element with another element. See {@link #alignTo} for more info on the\r
  85      * supported position values.\r
  86      * @param {Mixed} element The element to align to.\r
  87      * @param {String} position The position to align to.\r
  88      * @param {Array} offsets (optional) Offset the positioning by [x, y]\r
  89      * @return {Array} [x, y]\r
  90      */\r
  91     getAlignToXY : function(el, p, o){      \r
  92         el = Ext.get(el);\r
  93         \r
  94         if(!el || !el.dom){\r
  95             throw "Element.alignToXY with an element that doesn't exist";\r
  96         }\r
  97         \r
  98         o = o || [0,0];\r
  99         p = (p == "?" ? "tl-bl?" : (!/-/.test(p) && p !== "" ? "tl-" + p : p || "tl-bl")).toLowerCase();       \r
 100                 \r
 101         var me = this,\r
 102                 d = me.dom,\r
 103                 a1,\r
 104                 a2,\r
 105                 x,\r
 106                 y,\r
 107                 //constrain the aligned el to viewport if necessary\r
 108                 w,\r
 109                 h,\r
 110                 r,\r
 111                 dw = Ext.lib.Dom.getViewWidth() -10, // 10px of margin for ie\r
 112                 dh = Ext.lib.Dom.getViewHeight()-10, // 10px of margin for ie\r
 113                 p1y,\r
 114                 p1x,            \r
 115                 p2y,\r
 116                 p2x,\r
 117                 swapY,\r
 118                 swapX,\r
 119                 doc = document,\r
 120                 docElement = doc.documentElement,\r
 121                 docBody = doc.body,\r
 122                 scrollX = (docElement.scrollLeft || docBody.scrollLeft || 0)+5,\r
 123                 scrollY = (docElement.scrollTop || docBody.scrollTop || 0)+5,\r
 124                 c = false, //constrain to viewport\r
 125                 p1 = "", \r
 126                 p2 = "",\r
 127                 m = p.match(/^([a-z]+)-([a-z]+)(\?)?$/);\r
 128         \r
 129         if(!m){\r
 130            throw "Element.alignTo with an invalid alignment " + p;\r
 131         }\r
 132         \r
 133         p1 = m[1]; \r
 134         p2 = m[2]; \r
 135         c = !!m[3];\r
 136 \r
 137         //Subtract the aligned el's internal xy from the target's offset xy\r
 138         //plus custom offset to get the aligned el's new offset xy\r
 139         a1 = me.getAnchorXY(p1, true);\r
 140         a2 = el.getAnchorXY(p2, false);\r
 141 \r
 142         x = a2[0] - a1[0] + o[0];\r
 143         y = a2[1] - a1[1] + o[1];\r
 144 \r
 145         if(c){    \r
 146                w = me.getWidth();\r
 147            h = me.getHeight();\r
 148            r = el.getRegion();       \r
 149            //If we are at a viewport boundary and the aligned el is anchored on a target border that is\r
 150            //perpendicular to the vp border, allow the aligned el to slide on that border,\r
 151            //otherwise swap the aligned el to the opposite border of the target.\r
 152            p1y = p1.charAt(0);\r
 153            p1x = p1.charAt(p1.length-1);\r
 154            p2y = p2.charAt(0);\r
 155            p2x = p2.charAt(p2.length-1);\r
 156            swapY = ((p1y=="t" && p2y=="b") || (p1y=="b" && p2y=="t"));\r
 157            swapX = ((p1x=="r" && p2x=="l") || (p1x=="l" && p2x=="r"));          \r
 158            \r
 159 \r
 160            if (x + w > dw + scrollX) {\r
 161                 x = swapX ? r.left-w : dw+scrollX-w;\r
 162            }\r
 163            if (x < scrollX) {\r
 164                x = swapX ? r.right : scrollX;\r
 165            }\r
 166            if (y + h > dh + scrollY) {\r
 167                 y = swapY ? r.top-h : dh+scrollY-h;\r
 168             }\r
 169            if (y < scrollY){\r
 170                y = swapY ? r.bottom : scrollY;\r
 171            }\r
 172         }\r
 173         return [x,y];\r
 174     },\r
 175 \r
 176     /**\r
 177      * Aligns this element with another element relative to the specified anchor points. If the other element is the\r
 178      * document it aligns it to the viewport.\r
 179      * The position parameter is optional, and can be specified in any one of the following formats:\r
 180      * <ul>\r
 181      *   <li><b>Blank</b>: Defaults to aligning the element's top-left corner to the target's bottom-left corner ("tl-bl").</li>\r
 182      *   <li><b>One anchor (deprecated)</b>: The passed anchor position is used as the target element's anchor point.\r
 183      *       The element being aligned will position its top-left corner (tl) to that point.  <i>This method has been\r
 184      *       deprecated in favor of the newer two anchor syntax below</i>.</li>\r
 185      *   <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
 186      *       element's anchor point, and the second value is used as the target's anchor point.</li>\r
 187      * </ul>\r
 188      * In addition to the anchor points, the position parameter also supports the "?" character.  If "?" is passed at the end of\r
 189      * the position string, the element will attempt to align as specified, but the position will be adjusted to constrain to\r
 190      * the viewport if necessary.  Note that the element being aligned might be swapped to align to a different position than\r
 191      * that specified in order to enforce the viewport constraints.\r
 192      * Following are all of the supported anchor positions:\r
 193 <pre>\r
 194 Value  Description\r
 195 -----  -----------------------------\r
 196 tl     The top left corner (default)\r
 197 t      The center of the top edge\r
 198 tr     The top right corner\r
 199 l      The center of the left edge\r
 200 c      In the center of the element\r
 201 r      The center of the right edge\r
 202 bl     The bottom left corner\r
 203 b      The center of the bottom edge\r
 204 br     The bottom right corner\r
 205 </pre>\r
 206 Example Usage:\r
 207 <pre><code>\r
 208 // align el to other-el using the default positioning ("tl-bl", non-constrained)\r
 209 el.alignTo("other-el");\r
 210 \r
 211 // align the top left corner of el with the top right corner of other-el (constrained to viewport)\r
 212 el.alignTo("other-el", "tr?");\r
 213 \r
 214 // align the bottom right corner of el with the center left edge of other-el\r
 215 el.alignTo("other-el", "br-l?");\r
 216 \r
 217 // align the center of el with the bottom left corner of other-el and\r
 218 // adjust the x position by -6 pixels (and the y position by 0)\r
 219 el.alignTo("other-el", "c-bl", [-6, 0]);\r
 220 </code></pre>\r
 221      * @param {Mixed} element The element to align to.\r
 222      * @param {String} position The position to align to.\r
 223      * @param {Array} offsets (optional) Offset the positioning by [x, y]\r
 224      * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object\r
 225      * @return {Ext.Element} this\r
 226      */\r
 227     alignTo : function(element, position, offsets, animate){\r
 228             var me = this;\r
 229         return me.setXY(me.getAlignToXY(element, position, offsets),\r
 230                                 me.preanim && !!animate ? me.preanim(arguments, 3) : false);\r
 231     },\r
 232     \r
 233     // private ==>  used outside of core\r
 234     adjustForConstraints : function(xy, parent, offsets){\r
 235         return this.getConstrainToXY(parent || document, false, offsets, xy) ||  xy;\r
 236     },\r
 237 \r
 238     // private ==>  used outside of core\r
 239     getConstrainToXY : function(el, local, offsets, proposedXY){   \r
 240             var os = {top:0, left:0, bottom:0, right: 0};\r
 241 \r
 242         return function(el, local, offsets, proposedXY){\r
 243             el = Ext.get(el);\r
 244             offsets = offsets ? Ext.applyIf(offsets, os) : os;\r
 245 \r
 246             var vw, vh, vx = 0, vy = 0;\r
 247             if(el.dom == document.body || el.dom == document){\r
 248                 vw =Ext.lib.Dom.getViewWidth();\r
 249                 vh = Ext.lib.Dom.getViewHeight();\r
 250             }else{\r
 251                 vw = el.dom.clientWidth;\r
 252                 vh = el.dom.clientHeight;\r
 253                 if(!local){\r
 254                     var vxy = el.getXY();\r
 255                     vx = vxy[0];\r
 256                     vy = vxy[1];\r
 257                 }\r
 258             }\r
 259 \r
 260             var s = el.getScroll();\r
 261 \r
 262             vx += offsets.left + s.left;\r
 263             vy += offsets.top + s.top;\r
 264 \r
 265             vw -= offsets.right;\r
 266             vh -= offsets.bottom;\r
 267 \r
 268             var vr = vx+vw;\r
 269             var vb = vy+vh;\r
 270 \r
 271             var xy = proposedXY || (!local ? this.getXY() : [this.getLeft(true), this.getTop(true)]);\r
 272             var x = xy[0], y = xy[1];\r
 273             var w = this.dom.offsetWidth, h = this.dom.offsetHeight;\r
 274 \r
 275             // only move it if it needs it\r
 276             var moved = false;\r
 277 \r
 278             // first validate right/bottom\r
 279             if((x + w) > vr){\r
 280                 x = vr - w;\r
 281                 moved = true;\r
 282             }\r
 283             if((y + h) > vb){\r
 284                 y = vb - h;\r
 285                 moved = true;\r
 286             }\r
 287             // then make sure top/left isn't negative\r
 288             if(x < vx){\r
 289                 x = vx;\r
 290                 moved = true;\r
 291             }\r
 292             if(y < vy){\r
 293                 y = vy;\r
 294                 moved = true;\r
 295             }\r
 296             return moved ? [x, y] : false;\r
 297         };\r
 298     }(),\r
 299             \r
 300             \r
 301                 \r
 302 //         el = Ext.get(el);\r
 303 //         offsets = Ext.applyIf(offsets || {}, {top : 0, left : 0, bottom : 0, right : 0});\r
 304 \r
 305 //         var  me = this,\r
 306 //              doc = document,\r
 307 //              s = el.getScroll(),\r
 308 //              vxy = el.getXY(),\r
 309 //              vx = offsets.left + s.left, \r
 310 //              vy = offsets.top + s.top,               \r
 311 //              vw = -offsets.right, \r
 312 //              vh = -offsets.bottom, \r
 313 //              vr,\r
 314 //              vb,\r
 315 //              xy = proposedXY || (!local ? me.getXY() : [me.getLeft(true), me.getTop(true)]),\r
 316 //              x = xy[0],\r
 317 //              y = xy[1],\r
 318 //              w = me.dom.offsetWidth, h = me.dom.offsetHeight,\r
 319 //              moved = false; // only move it if it needs it\r
 320 //       \r
 321 //              \r
 322 //         if(el.dom == doc.body || el.dom == doc){\r
 323 //             vw += Ext.lib.Dom.getViewWidth();\r
 324 //             vh += Ext.lib.Dom.getViewHeight();\r
 325 //         }else{\r
 326 //             vw += el.dom.clientWidth;\r
 327 //             vh += el.dom.clientHeight;\r
 328 //             if(!local){                    \r
 329 //                 vx += vxy[0];\r
 330 //                 vy += vxy[1];\r
 331 //             }\r
 332 //         }\r
 333 \r
 334 //         // first validate right/bottom\r
 335 //         if(x + w > vx + vw){\r
 336 //             x = vx + vw - w;\r
 337 //             moved = true;\r
 338 //         }\r
 339 //         if(y + h > vy + vh){\r
 340 //             y = vy + vh - h;\r
 341 //             moved = true;\r
 342 //         }\r
 343 //         // then make sure top/left isn't negative\r
 344 //         if(x < vx){\r
 345 //             x = vx;\r
 346 //             moved = true;\r
 347 //         }\r
 348 //         if(y < vy){\r
 349 //             y = vy;\r
 350 //             moved = true;\r
 351 //         }\r
 352 //         return moved ? [x, y] : false;\r
 353 //    },\r
 354     \r
 355     /**\r
 356     * Calculates the x, y to center this element on the screen\r
 357     * @return {Array} The x, y values [x, y]\r
 358     */\r
 359     getCenterXY : function(){\r
 360         return this.getAlignToXY(document, 'c-c');\r
 361     },\r
 362 \r
 363     /**\r
 364     * Centers the Element in either the viewport, or another Element.\r
 365     * @param {Mixed} centerIn (optional) The element in which to center the element.\r
 366     */\r
 367     center : function(centerIn){\r
 368         return this.alignTo(centerIn || document, 'c-c');        \r
 369     }    \r
 370 });\r