/**
* @class Ext.util.Region
* @extends Object
*
- * Represents a rectangular region and provides a number of utility methods
- * to compare regions.
+ * <p>This class represents a rectangular region in X,Y space, and performs geometric
+ * transformations or tests upon the region.</p>
+ * <p>This class may be used to compare the document regions occupied by elements.</p>
*/
Ext.define('Ext.util.Region', {
@@ -13,21 +31,21 @@ Ext.define('Ext.util.Region', {
requires: ['Ext.util.Offset'],
statics: {
- /**
+ /**
* @static
- * @param {Mixed} el A string, DomElement or Ext.core.Element representing an element
- * on the page.
- * @returns {Ext.util.Region} region
* Retrieves an Ext.util.Region for a particular element.
+ * @param {Mixed} el An element ID, htmlElement or Ext.core.Element representing an element in the document.
+ * @returns {Ext.util.Region} region
*/
getRegion: function(el) {
return Ext.fly(el).getPageBox(true);
},
- /**
+ /**
* @static
- * @param {Object} o An object with top, right, bottom, left properties
- * @return {Ext.util.Region} region The region constructed based on the passed object
+ * Creates a Region from a "box" Object which contains four numeric properties <code>top</code>, <code>right</code>, <code>bottom</code> and <code>left</code>.
+ * @param {Object} o An object with <code>top</code>, <code>right</code>, <code>bottom</code> and <code>left</code> properties.
+ * @return {Ext.util.Region} region The Region constructed based on the passed object
*/
from: function(o) {
return new this(o.top, o.right, o.bottom, o.left);
@@ -36,12 +54,12 @@ Ext.define('Ext.util.Region', {
/* End Definitions */
- /**
- * @constructor
- * @param {Number} top Top
- * @param {Number} right Right
- * @param {Number} bottom Bottom
- * @param {Number} left Left
+ /**
+ * Creates a region from the bounding sides.
+ * @param {Number} top Top The topmost pixel of the Region.
+ * @param {Number} right Right The rightmost pixel of the Region.
+ * @param {Number} bottom Bottom The bottom pixel of the Region.
+ * @param {Number} left Left The leftmost pixel of the Region.
*/
constructor : function(t, r, b, l) {
var me = this;
@@ -51,7 +69,7 @@ Ext.define('Ext.util.Region', {
me.x = me.left = me[0] = l;
},
- /**
+ /**
* Checks if this region completely contains the region that is passed in.
* @param {Ext.util.Region} region
*/
@@ -64,7 +82,7 @@ Ext.define('Ext.util.Region', {
},
- /**
+ /**
* Checks if this region intersects the region passed in.
* @param {Ext.util.Region} region
* @return {Ext.util.Region/Boolean} Returns the intersected region or false if there is no intersection.
@@ -84,7 +102,7 @@ Ext.define('Ext.util.Region', {
}
},
- /**
+ /**
* Returns the smallest region that contains the current AND targetRegion.
* @param {Ext.util.Region} region
*/
@@ -98,7 +116,7 @@ Ext.define('Ext.util.Region', {
return new this.self(t, r, b, l);
},
- /**
+ /**
* Modifies the current region to be constrained to the targetRegion.
* @param {Ext.util.Region} targetRegion
*/
@@ -112,7 +130,7 @@ Ext.define('Ext.util.Region', {
return me;
},
- /**
+ /**
* Modifies the current region to be adjusted by offsets.
* @param {Number} top top offset
* @param {Number} right right offset
@@ -128,7 +146,7 @@ Ext.define('Ext.util.Region', {
return me;
},
- /**
+ /**
* Get the offset amount of a point outside the region
* @param {String} axis optional
* @param {Ext.util.Point} p the point
@@ -151,7 +169,7 @@ Ext.define('Ext.util.Region', {
},
- /**
+ /**
* Get the offset amount on the x-axis
* @param {Number} p the offset
* @return {Number}
@@ -166,7 +184,7 @@ Ext.define('Ext.util.Region', {
return 0;
},
- /**
+ /**
* Get the offset amount on the y-axis
* @param {Number} p the offset
* @return {Number}
@@ -181,7 +199,7 @@ Ext.define('Ext.util.Region', {
return 0;
},
- /**
+ /**
* Check whether the point / offset is out of bound
* @param {String} axis optional
* @param {Ext.util.Point/Number} p the point / offset
@@ -200,7 +218,7 @@ Ext.define('Ext.util.Region', {
}
},
- /**
+ /**
* Check whether the offset is out of bound in the x-axis
* @param {Number} p the offset
* @return {Boolean}
@@ -209,7 +227,7 @@ Ext.define('Ext.util.Region', {
return (p < this.x || p > this.right);
},
- /**
+ /**
* Check whether the offset is out of bound in the y-axis
* @param {Number} p the offset
* @return {Boolean}
@@ -304,18 +322,18 @@ Ext.define('Ext.util.Region', {
};
},
- /**
- * Copy a new instance
+ /**
+ * Create a copy of this Region.
* @return {Ext.util.Region}
*/
copy: function() {
return new this.self(this.y, this.right, this.bottom, this.x);
},
- /**
+ /**
* Copy the values of another Region to this Region
* @param {Region} The region to copy from.
- * @return {Ext.util.Point} this This point
+ * @return {Ext.util.Region} This Region
*/
copyFrom: function(p) {
var me = this;
@@ -327,16 +345,15 @@ Ext.define('Ext.util.Region', {
return this;
},
- /**
- * Dump this to an eye-friendly string, great for debugging
+ /*
+ * Dump this to an eye-friendly string, great for debugging
* @return {String}
*/
toString: function() {
return "Region[" + this.top + "," + this.right + "," + this.bottom + "," + this.left + "]";
},
-
- /**
+ /**
* Translate this region by the given offset amount
* @param {Ext.util.Offset/Object} offset Object containing the <code>x</code> and <code>y</code> properties.
* Or the x value is using the two argument form.
@@ -357,7 +374,7 @@ Ext.define('Ext.util.Region', {
return me;
},
- /**
+ /**
* Round all the properties of this region
* @return {Ext.util.Region} this This Region
*/
@@ -371,7 +388,7 @@ Ext.define('Ext.util.Region', {
return me;
},
- /**
+ /**
* Check whether this region is equivalent to the given region
* @param {Ext.util.Region} region The region to compare with
* @return {Boolean}
@@ -380,4 +397,6 @@ Ext.define('Ext.util.Region', {
return (this.top == region.top && this.right == region.right && this.bottom == region.bottom && this.left == region.left);
}
});
-