docs/source/Element.alignment.html

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