src/core/Element.alignment.js

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