add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / util / Point.js

/**\r
 * Represents a 2D point with x and y properties, useful for comparison and instantiation\r
 * from an event:\r
 *\r
 *     var point = Ext.util.Point.fromEvent(e);\r
 */\r
Ext.define('Ext.util.Point', {\r
    extend: 'Ext.util.Region',\r
\r
    radianToDegreeConstant: 180 / Math.PI,\r
    \r
    origin: { x: 0, y: 0 },\r
\r
    statics: {\r
        /**\r
         * Returns a new instance of {@link Ext.util.Point} based on the `pageX` / `pageY` values of the given event.\r
         * @static\r
         * @param {Event} e The event.\r
         * @return {Ext.util.Point}\r
         */\r
        fromEvent: function(e) {\r
            var changedTouches = e.changedTouches,\r
                touch = (changedTouches && changedTouches.length > 0) ? changedTouches[0] : e;\r
\r
            return this.fromTouch(touch);\r
        },\r
\r
        /**\r
         * Returns a new instance of {@link Ext.util.Point} based on the `pageX` / `pageY` values of the given touch.\r
         * @static\r
         * @param {Event} touch\r
         * @return {Ext.util.Point}\r
         */\r
        fromTouch: function(touch) {\r
            return new this(touch.pageX, touch.pageY);\r
        },\r
\r
        /**\r
         * Returns a new point from an object that has `x` and `y` properties, if that object is not an instance\r
         * of {@link Ext.util.Point}. Otherwise, returns the given point itself.\r
         * @param {Object} object\r
         * @return {Ext.util.Point}\r
         */\r
        from: function(object) {\r
            if (!object) {\r
                return new this(0, 0);\r
            }\r
\r
            if (!(object instanceof this)) {\r
                return new this(object.x, object.y);\r
            }\r
\r
            return object;\r
        }\r
    },\r
\r
    /**\r
     * Creates point on 2D plane.\r
     * @param {Number} [x=0] X coordinate.\r
     * @param {Number} [y=0] Y coordinate.\r
     */\r
    constructor: function(x, y) {\r
        if (x == null) {\r
            x = 0;\r
        }\r
\r
        if (y == null) {\r
            y = 0;\r
        }\r
\r
        this.callParent([y, x, y, x]);\r
    },\r
\r
    /**\r
     * Copy a new instance of this point.\r
     * @return {Ext.util.Point} The new point.\r
     */\r
    clone: function() {\r
        return new this.self(this.x, this.y);\r
    },\r
\r
    /**\r
     * Clones this Point.\r
     * @deprecated 2.0.0 Please use {@link #clone} instead.\r
     * @return {Ext.util.Point} The new point.\r
     */\r
    copy: function() {\r
        return this.clone.apply(this, arguments);\r
    },\r
\r
    /**\r
     * Copy the `x` and `y` values of another point / object to this point itself.\r
     * @param {Ext.util.Point/Object} point.\r
     * @return {Ext.util.Point} This point.\r
     */\r
    copyFrom: function(point) {\r
        this.x = point.x;\r
        this.y = point.y;\r
\r
        return this;\r
    },\r
\r
    /**\r
     * Returns a human-eye-friendly string that represents this point,\r
     * useful for debugging.\r
     * @return {String} For example `Point[12,8]`.\r
     */\r
    toString: function() {\r
        return "Point[" + this.x + "," + this.y + "]";\r
    },\r
\r
    /**\r
     * Compare this point and another point.\r
     * @param {Ext.util.Point/Object} point The point to compare with, either an instance\r
     * of {@link Ext.util.Point} or an object with `x` and `y` properties.\r
     * @return {Boolean} Returns whether they are equivalent.\r
     */\r
    equals: function(point) {\r
        return (this.x === point.x && this.y === point.y);\r
    },\r
\r
    /**\r
     * Returns `true` if the passed point is within a certain distance of this point.\r
     * @param {Ext.util.Point/Object} point The point to check with, either an instance\r
     * of {@link Ext.util.Point} or an object with `x` and `y` properties.\r
     * @param {Object/Number} threshold Can be either an object with `x` and `y` properties or a number.\r
     * @return {Boolean}\r
     */\r
    isCloseTo: function(point, threshold) {\r
        if (typeof threshold == 'number') {\r
            return this.getDistanceTo(point) <= threshold;\r
        }\r
\r
        var x = point.x,\r
            y = point.y,\r
            thresholdX = threshold.x,\r
            thresholdY = threshold.y;\r
\r
        return (this.x <= x + thresholdX && this.x >= x - thresholdX &&\r
                this.y <= y + thresholdY && this.y >= y - thresholdY);\r
    },\r
\r
    /**\r
     * Returns `true` if this point is close to another one.\r
     * @deprecated 2.0.0 Please use {@link #isCloseTo} instead.\r
     * @return {Boolean}\r
     */\r
    isWithin: function() {\r
        return this.isCloseTo.apply(this, arguments);\r
    },\r
\r
    /**\r
     * Determins whether this Point contained by the passed Region, Component or element.\r
     * @param {Ext.util.Region/Ext.Component/Ext.dom.Element/HTMLElement} region\r
     * The rectangle to check that this Point is within.\r
     * @return {Boolean}\r
     */\r
    isContainedBy: function(region) {\r
        if (!(region instanceof Ext.util.Region)) {\r
            region = Ext.get(region.el || region).getRegion();\r
        }\r
        return region.contains(this);\r
    },\r
\r
    /**\r
     * Compare this point with another point when the `x` and `y` values of both points are rounded. For example:\r
     * [100.3,199.8] will equals to [100, 200].\r
     * @param {Ext.util.Point/Object} point The point to compare with, either an instance\r
     * of Ext.util.Point or an object with `x` and `y` properties.\r
     * @return {Boolean}\r
     */\r
    roundedEquals: function(point) {\r
        if (!point || typeof point !== 'object') {\r
            point = this.origin;\r
        }\r
\r
        return (Math.round(this.x) === Math.round(point.x) &&\r
                Math.round(this.y) === Math.round(point.y));\r
    },\r
\r
    getDistanceTo: function(point) {\r
        if (!point || typeof point !== 'object') {\r
            point = this.origin;\r
        }\r
\r
        var deltaX = this.x - point.x,\r
            deltaY = this.y - point.y;\r
\r
        return Math.sqrt(deltaX * deltaX + deltaY * deltaY);\r
    },\r
\r
    getAngleTo: function(point) {\r
        if (!point || typeof point !== 'object') {\r
            point = this.origin;\r
        }\r
\r
        var deltaX = this.x - point.x,\r
            deltaY = this.y - point.y;\r
\r
        return Math.atan2(deltaY, deltaX) * this.radianToDegreeConstant;\r
    }\r
}, function() {\r
    /**\r
     * @method\r
     * Alias for {@link #translateBy}\r
     * @inheritdoc Ext.util.Region#translateBy\r
     */\r
    this.prototype.translate = this.prototype.translateBy;\r
});\r