docs/source/Element.alignment.html

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