docs/source/Element.alignment.html

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