src/util/Region.js

   1 /**
   2  * @class Ext.util.Region
   3  * @extends Object
   4  *
   5  * Represents a rectangular region and provides a number of utility methods
   6  * to compare regions.
   7  */
   8
   9 Ext.define('Ext.util.Region', {
  10
  11     /* Begin Definitions */
  12
  13     requires: ['Ext.util.Offset'],
  14
  15     statics: {
  16         /**
  17          * @static
  18          * @param {Mixed} el A string, DomElement or Ext.core.Element representing an element
  19          * on the page.
  20          * @returns {Ext.util.Region} region
  21          * Retrieves an Ext.util.Region for a particular element.
  22          */
  23         getRegion: function(el) {
  24             return Ext.fly(el).getPageBox(true);
  25         },
  26
  27         /**
  28          * @static
  29          * @param {Object} o An object with top, right, bottom, left properties
  30          * @return {Ext.util.Region} region The region constructed based on the passed object
  31          */
  32         from: function(o) {
  33             return new this(o.top, o.right, o.bottom, o.left);
  34         }
  35     },
  36
  37     /* End Definitions */
  38
  39     /**
  40      * @constructor
  41      * @param {Number} top Top
  42      * @param {Number} right Right
  43      * @param {Number} bottom Bottom
  44      * @param {Number} left Left
  45      */
  46     constructor : function(t, r, b, l) {
  47         var me = this;
  48         me.y = me.top = me[1] = t;
  49         me.right = r;
  50         me.bottom = b;
  51         me.x = me.left = me[0] = l;
  52     },
  53
  54     /**
  55      * Checks if this region completely contains the region that is passed in.
  56      * @param {Ext.util.Region} region
  57      */
  58     contains : function(region) {
  59         var me = this;
  60         return (region.x >= me.x &&
  61                 region.right <= me.right &&
  62                 region.y >= me.y &&
  63                 region.bottom <= me.bottom);
  64
  65     },
  66
  67     /**
  68      * Checks if this region intersects the region passed in.
  69      * @param {Ext.util.Region} region
  70      * @return {Ext.util.Region/Boolean} Returns the intersected region or false if there is no intersection.
  71      */
  72     intersect : function(region) {
  73         var me = this,
  74             t = Math.max(me.y, region.y),
  75             r = Math.min(me.right, region.right),
  76             b = Math.min(me.bottom, region.bottom),
  77             l = Math.max(me.x, region.x);
  78
  79         if (b > t && r > l) {
  80             return new this.self(t, r, b, l);
  81         }
  82         else {
  83             return false;
  84         }
  85     },
  86
  87     /**
  88      * Returns the smallest region that contains the current AND targetRegion.
  89      * @param {Ext.util.Region} region
  90      */
  91     union : function(region) {
  92         var me = this,
  93             t = Math.min(me.y, region.y),
  94             r = Math.max(me.right, region.right),
  95             b = Math.max(me.bottom, region.bottom),
  96             l = Math.min(me.x, region.x);
  97
  98         return new this.self(t, r, b, l);
  99     },
 100
 101     /**
 102      * Modifies the current region to be constrained to the targetRegion.
 103      * @param {Ext.util.Region} targetRegion
 104      */
 105     constrainTo : function(r) {
 106         var me = this,
 107             constrain = Ext.Number.constrain;
 108         me.top = me.y = constrain(me.top, r.y, r.bottom);
 109         me.bottom = constrain(me.bottom, r.y, r.bottom);
 110         me.left = me.x = constrain(me.left, r.x, r.right);
 111         me.right = constrain(me.right, r.x, r.right);
 112         return me;
 113     },
 114
 115     /**
 116      * Modifies the current region to be adjusted by offsets.
 117      * @param {Number} top top offset
 118      * @param {Number} right right offset
 119      * @param {Number} bottom bottom offset
 120      * @param {Number} left left offset
 121      */
 122     adjust : function(t, r, b, l) {
 123         var me = this;
 124         me.top = me.y += t;
 125         me.left = me.x += l;
 126         me.right += r;
 127         me.bottom += b;
 128         return me;
 129     },
 130
 131     /**
 132      * Get the offset amount of a point outside the region
 133      * @param {String} axis optional
 134      * @param {Ext.util.Point} p the point
 135      * @return {Ext.util.Offset}
 136      */
 137     getOutOfBoundOffset: function(axis, p) {
 138         if (!Ext.isObject(axis)) {
 139             if (axis == 'x') {
 140                 return this.getOutOfBoundOffsetX(p);
 141             } else {
 142                 return this.getOutOfBoundOffsetY(p);
 143             }
 144         } else {
 145             p = axis;
 146             var d = Ext.create('Ext.util.Offset');
 147             d.x = this.getOutOfBoundOffsetX(p.x);
 148             d.y = this.getOutOfBoundOffsetY(p.y);
 149             return d;
 150         }
 151
 152     },
 153
 154     /**
 155      * Get the offset amount on the x-axis
 156      * @param {Number} p the offset
 157      * @return {Number}
 158      */
 159     getOutOfBoundOffsetX: function(p) {
 160         if (p <= this.x) {
 161             return this.x - p;
 162         } else if (p >= this.right) {
 163             return this.right - p;
 164         }
 165
 166         return 0;
 167     },
 168
 169     /**
 170      * Get the offset amount on the y-axis
 171      * @param {Number} p the offset
 172      * @return {Number}
 173      */
 174     getOutOfBoundOffsetY: function(p) {
 175         if (p <= this.y) {
 176             return this.y - p;
 177         } else if (p >= this.bottom) {
 178             return this.bottom - p;
 179         }
 180
 181         return 0;
 182     },
 183
 184     /**
 185      * Check whether the point / offset is out of bound
 186      * @param {String} axis optional
 187      * @param {Ext.util.Point/Number} p the point / offset
 188      * @return {Boolean}
 189      */
 190     isOutOfBound: function(axis, p) {
 191         if (!Ext.isObject(axis)) {
 192             if (axis == 'x') {
 193                 return this.isOutOfBoundX(p);
 194             } else {
 195                 return this.isOutOfBoundY(p);
 196             }
 197         } else {
 198             p = axis;
 199             return (this.isOutOfBoundX(p.x) || this.isOutOfBoundY(p.y));
 200         }
 201     },
 202
 203     /**
 204      * Check whether the offset is out of bound in the x-axis
 205      * @param {Number} p the offset
 206      * @return {Boolean}
 207      */
 208     isOutOfBoundX: function(p) {
 209         return (p < this.x || p > this.right);
 210     },
 211
 212     /**
 213      * Check whether the offset is out of bound in the y-axis
 214      * @param {Number} p the offset
 215      * @return {Boolean}
 216      */
 217     isOutOfBoundY: function(p) {
 218         return (p < this.y || p > this.bottom);
 219     },
 220
 221     /*
 222      * Restrict a point within the region by a certain factor.
 223      * @param {String} axis Optional
 224      * @param {Ext.util.Point/Ext.util.Offset/Object} p
 225      * @param {Number} factor
 226      * @return {Ext.util.Point/Ext.util.Offset/Object/Number}
 227      */
 228     restrict: function(axis, p, factor) {
 229         if (Ext.isObject(axis)) {
 230             var newP;
 231
 232             factor = p;
 233             p = axis;
 234
 235             if (p.copy) {
 236                 newP = p.copy();
 237             }
 238             else {
 239                 newP = {
 240                     x: p.x,
 241                     y: p.y
 242                 };
 243             }
 244
 245             newP.x = this.restrictX(p.x, factor);
 246             newP.y = this.restrictY(p.y, factor);
 247             return newP;
 248         } else {
 249             if (axis == 'x') {
 250                 return this.restrictX(p, factor);
 251             } else {
 252                 return this.restrictY(p, factor);
 253             }
 254         }
 255     },
 256
 257     /*
 258      * Restrict an offset within the region by a certain factor, on the x-axis
 259      * @param {Number} p
 260      * @param {Number} factor The factor, optional, defaults to 1
 261      * @return
 262      */
 263     restrictX : function(p, factor) {
 264         if (!factor) {
 265             factor = 1;
 266         }
 267
 268         if (p <= this.x) {
 269             p -= (p - this.x) * factor;
 270         }
 271         else if (p >= this.right) {
 272             p -= (p - this.right) * factor;
 273         }
 274         return p;
 275     },
 276
 277     /*
 278      * Restrict an offset within the region by a certain factor, on the y-axis
 279      * @param {Number} p
 280      * @param {Number} factor The factor, optional, defaults to 1
 281      */
 282     restrictY : function(p, factor) {
 283         if (!factor) {
 284             factor = 1;
 285         }
 286
 287         if (p <= this.y) {
 288             p -= (p - this.y) * factor;
 289         }
 290         else if (p >= this.bottom) {
 291             p -= (p - this.bottom) * factor;
 292         }
 293         return p;
 294     },
 295
 296     /*
 297      * Get the width / height of this region
 298      * @return {Object} an object with width and height properties
 299      */
 300     getSize: function() {
 301         return {
 302             width: this.right - this.x,
 303             height: this.bottom - this.y
 304         };
 305     },
 306
 307     /**
 308      * Copy a new instance
 309      * @return {Ext.util.Region}
 310      */
 311     copy: function() {
 312         return new this.self(this.y, this.right, this.bottom, this.x);
 313     },
 314
 315     /**
 316      * Copy the values of another Region to this Region
 317      * @param {Region} The region to copy from.
 318      * @return {Ext.util.Point} this This point
 319      */
 320     copyFrom: function(p) {
 321         var me = this;
 322         me.top = me.y = me[1] = p.y;
 323         me.right = p.right;
 324         me.bottom = p.bottom;
 325         me.left = me.x = me[0] = p.x;
 326
 327         return this;
 328     },
 329
 330     /**
 331      * Dump this to an eye-friendly string, great for debugging
 332      * @return {String}
 333      */
 334     toString: function() {
 335         return "Region[" + this.top + "," + this.right + "," + this.bottom + "," + this.left + "]";
 336     },
 337
 338
 339     /**
 340      * Translate this region by the given offset amount
 341      * @param {Ext.util.Offset/Object} offset Object containing the <code>x</code> and <code>y</code> properties.
 342      * Or the x value is using the two argument form.
 343      * @param {Number} The y value unless using an Offset object.
 344      * @return {Ext.util.Region} this This Region
 345      */
 346     translateBy: function(x, y) {
 347         if (arguments.length == 1) {
 348             y = x.y;
 349             x = x.x;
 350         }
 351         var me = this;
 352         me.top = me.y += y;
 353         me.right += x;
 354         me.bottom += y;
 355         me.left = me.x += x;
 356
 357         return me;
 358     },
 359
 360     /**
 361      * Round all the properties of this region
 362      * @return {Ext.util.Region} this This Region
 363      */
 364     round: function() {
 365         var me = this;
 366         me.top = me.y = Math.round(me.y);
 367         me.right = Math.round(me.right);
 368         me.bottom = Math.round(me.bottom);
 369         me.left = me.x = Math.round(me.x);
 370
 371         return me;
 372     },
 373
 374     /**
 375      * Check whether this region is equivalent to the given region
 376      * @param {Ext.util.Region} region The region to compare with
 377      * @return {Boolean}
 378      */
 379     equals: function(region) {
 380         return (this.top == region.top && this.right == region.right && this.bottom == region.bottom && this.left == region.left);
 381     }
 382 });