src/src/util/Point.js

   1 /**
   2  * Represents a 2D point with x and y properties, useful for comparison and instantiation
   3  * from an event:
   4  *
   5  *     var point = Ext.util.Point.fromEvent(e);
   6  */
   7 Ext.define('Ext.util.Point', {
   8
   9     radianToDegreeConstant: 180 / Math.PI,
  10
  11     statics: {
  12         /**
  13          * Returns a new instance of {@link Ext.util.Point} based on the `pageX` / `pageY` values of the given event.
  14          * @static
  15          * @param {Event} e The event.
  16          * @return {Ext.util.Point}
  17          */
  18         fromEvent: function(e) {
  19             var changedTouches = e.changedTouches,
  20                 touch = (changedTouches && changedTouches.length > 0) ? changedTouches[0] : e;
  21
  22             return this.fromTouch(touch);
  23         },
  24
  25         /**
  26          * Returns a new instance of {@link Ext.util.Point} based on the `pageX` / `pageY` values of the given touch.
  27          * @static
  28          * @param {Event} touch
  29          * @return {Ext.util.Point}
  30          */
  31         fromTouch: function(touch) {
  32             return new this(touch.pageX, touch.pageY);
  33         },
  34
  35         /**
  36          * Returns a new point from an object that has `x` and `y` properties, if that object is not an instance
  37          * of {@link Ext.util.Point}. Otherwise, returns the given point itself.
  38          * @param {Object} object
  39          * @return {Ext.util.Point}
  40          */
  41         from: function(object) {
  42             if (!object) {
  43                 return new this(0, 0);
  44             }
  45
  46             if (!(object instanceof this)) {
  47                 return new this(object.x, object.y);
  48             }
  49
  50             return object;
  51         }
  52     },
  53
  54     /**
  55      * Creates point on 2D plane.
  56      * @param {Number} [x=0] X coordinate.
  57      * @param {Number} [y=0] Y coordinate.
  58      */
  59     constructor: function(x, y) {
  60         if (typeof x == 'undefined') {
  61             x = 0;
  62         }
  63
  64         if (typeof y == 'undefined') {
  65             y = 0;
  66         }
  67
  68         this.x = x;
  69         this.y = y;
  70
  71         return this;
  72     },
  73
  74     /**
  75      * Copy a new instance of this point.
  76      * @return {Ext.util.Point} The new point.
  77      */
  78     clone: function() {
  79         return new this.self(this.x, this.y);
  80     },
  81
  82     /**
  83      * Clones this Point.
  84      * @deprecated 2.0.0 Please use {@link #clone} instead.
  85      * @return {Ext.util.Point} The new point.
  86      */
  87     copy: function() {
  88         return this.clone.apply(this, arguments);
  89     },
  90
  91     /**
  92      * Copy the `x` and `y` values of another point / object to this point itself.
  93      * @param {Ext.util.Point/Object} point.
  94      * @return {Ext.util.Point} This point.
  95      */
  96     copyFrom: function(point) {
  97         this.x = point.x;
  98         this.y = point.y;
  99
 100         return this;
 101     },
 102
 103     /**
 104      * Returns a human-eye-friendly string that represents this point,
 105      * useful for debugging.
 106      * @return {String} For example `Point[12,8]`.
 107      */
 108     toString: function() {
 109         return "Point[" + this.x + "," + this.y + "]";
 110     },
 111
 112     /**
 113      * Compare this point and another point.
 114      * @param {Ext.util.Point/Object} point The point to compare with, either an instance
 115      * of {@link Ext.util.Point} or an object with `x` and `y` properties.
 116      * @return {Boolean} Returns whether they are equivalent.
 117      */
 118     equals: function(point) {
 119         return (this.x === point.x && this.y === point.y);
 120     },
 121
 122     /**
 123      * Whether the given point is not away from this point within the given threshold amount.
 124      * @param {Ext.util.Point/Object} point The point to check with, either an instance
 125      * of {@link Ext.util.Point} or an object with `x` and `y` properties.
 126      * @param {Object/Number} threshold Can be either an object with `x` and `y` properties or a number.
 127      * @return {Boolean}
 128      */
 129     isCloseTo: function(point, threshold) {
 130         if (typeof threshold == 'number') {
 131             threshold = {x: threshold};
 132             threshold.y = threshold.x;
 133         }
 134
 135         var x = point.x,
 136             y = point.y,
 137             thresholdX = threshold.x,
 138             thresholdY = threshold.y;
 139
 140         return (this.x <= x + thresholdX && this.x >= x - thresholdX &&
 141                 this.y <= y + thresholdY && this.y >= y - thresholdY);
 142     },
 143
 144     /**
 145      * Returns `true` if this point is close to another one.
 146      * @deprecated 2.0.0 Please use {@link #isCloseTo} instead.
 147      * @return {Boolean}
 148      */
 149     isWithin: function() {
 150         return this.isCloseTo.apply(this, arguments);
 151     },
 152
 153     /**
 154      * Translate this point by the given amounts.
 155      * @param {Number} x Amount to translate in the x-axis.
 156      * @param {Number} y Amount to translate in the y-axis.
 157      * @return {Boolean}
 158      */
 159     translate: function(x, y) {
 160         this.x += x;
 161         this.y += y;
 162
 163         return this;
 164     },
 165
 166     /**
 167      * Compare this point with another point when the `x` and `y` values of both points are rounded. For example:
 168      * [100.3,199.8] will equals to [100, 200].
 169      * @param {Ext.util.Point/Object} point The point to compare with, either an instance
 170      * of Ext.util.Point or an object with `x` and `y` properties.
 171      * @return {Boolean}
 172      */
 173     roundedEquals: function(point) {
 174         if (typeof point != 'object') {
 175             point = { x: 0, y: 0};
 176         }
 177
 178         return (Math.round(this.x) === Math.round(point.x) &&
 179                 Math.round(this.y) === Math.round(point.y));
 180     },
 181
 182     getDistanceTo: function(point) {
 183         if (typeof point != 'object') {
 184             point = { x: 0, y: 0};
 185         }
 186
 187         var deltaX = this.x - point.x,
 188             deltaY = this.y - point.y;
 189
 190         return Math.sqrt(deltaX * deltaX + deltaY * deltaY);
 191     },
 192
 193     getAngleTo: function(point) {
 194         if (typeof point != 'object') {
 195             point = { x: 0, y: 0};
 196         }
 197
 198         var deltaX = this.x - point.x,
 199             deltaY = this.y - point.y;
 200
 201         return Math.atan2(deltaY, deltaX) * this.radianToDegreeConstant;
 202     }
 203 });