add extjs 6.0.1 sources

[extjs.git] / extjs / modern / modern / src / util / Geolocation.js

/**\r
 * Provides a cross browser class for retrieving location information.\r
 *\r
 * Based on the [Geolocation API Specification](http://dev.w3.org/geo/api/spec-source.html)\r
 *\r
 * When instantiated, by default this class immediately begins tracking location information,\r
 * firing a {@link #locationupdate} event when new location information is available.  To disable this\r
 * location tracking (which may be battery intensive on mobile devices), set {@link #autoUpdate} to `false`.\r
 *\r
 * When this is done, only calls to {@link #updateLocation} will trigger a location retrieval.\r
 *\r
 * A {@link #locationerror} event is raised when an error occurs retrieving the location, either due to a user\r
 * denying the application access to it, or the browser not supporting it.\r
 *\r
 * The below code shows a GeoLocation making a single retrieval of location information.\r
 *\r
 *     var geo = Ext.create('Ext.util.Geolocation', {\r
 *         autoUpdate: false,\r
 *         listeners: {\r
 *             locationupdate: function(geo) {\r
 *                 alert('New latitude: ' + geo.getLatitude());\r
 *             },\r
 *             locationerror: function(geo, bTimeout, bPermissionDenied, bLocationUnavailable, message) {\r
 *                 if(bTimeout){\r
 *                     alert('Timeout occurred.');\r
 *                 } else {\r
 *                     alert('Error occurred.');\r
 *                 }\r
 *             }\r
 *         }\r
 *     });\r
 *     geo.updateLocation();\r
 */\r
Ext.define('Ext.util.Geolocation', {\r
    extend: 'Ext.Evented',\r
    alternateClassName: ['Ext.util.GeoLocation'],\r
\r
    config: {\r
        /**\r
         * @event locationerror\r
         * Raised when a location retrieval operation failed.\r
         *\r
         * In the case of calling updateLocation, this event will be raised only once.\r
         *\r
         * If {@link #autoUpdate} is set to `true`, this event could be raised repeatedly.\r
         * The first error is relative to the moment {@link #autoUpdate} was set to `true`\r
         * (or this {@link Ext.util.Geolocation} was initialized with the {@link #autoUpdate} config option set to `true`).\r
         * Subsequent errors are relative to the moment when the device determines that it's position has changed.\r
         * @param {Ext.util.Geolocation} this\r
         * @param {Boolean} timeout\r
         * Boolean indicating a timeout occurred\r
         * @param {Boolean} permissionDenied\r
         * Boolean indicating the user denied the location request\r
         * @param {Boolean} locationUnavailable\r
         * Boolean indicating that the location of the device could not be determined.\r
         * For instance, one or more of the location providers used in the location acquisition\r
         * process reported an internal error that caused the process to fail entirely.\r
         * @param {String} message An error message describing the details of the error encountered.\r
         *\r
         * This attribute is primarily intended for debugging and should not be used\r
         * directly in an application user interface.\r
         */\r
\r
        /**\r
         * @event locationupdate\r
         * Raised when a location retrieval operation has been completed successfully.\r
         * @param {Ext.util.Geolocation} this\r
         * Retrieve the current location information from the GeoLocation object by using the read-only\r
         * properties: {@link #latitude}, {@link #longitude}, {@link #accuracy}, {@link #altitude}, {@link #altitudeAccuracy}, {@link #heading}, and {@link #speed}.\r
         */\r
\r
        /**\r
         * @cfg {Boolean} autoUpdate\r
         * When set to `true`, continually monitor the location of the device (beginning immediately)\r
         * and fire {@link #locationupdate} and {@link #locationerror} events.\r
         */\r
        autoUpdate: true,\r
\r
        /**\r
         * @cfg {Number} frequency\r
         * The frequency of each update if {@link #autoUpdate} is set to `true`.\r
         */\r
        frequency: 10000,\r
\r
        /**\r
         * @cfg {Number} latitude\r
         * Read-only property representing the last retrieved\r
         * geographical coordinate specified in degrees.\r
         * @readonly\r
         */\r
        latitude: null,\r
\r
        /**\r
         * @cfg {Number} longitude\r
         * Read-only property representing the last retrieved\r
         * geographical coordinate specified in degrees.\r
         * @readonly\r
         */\r
        longitude: null,\r
\r
        /**\r
         * @cfg {Number} accuracy\r
         * Read-only property representing the last retrieved\r
         * accuracy level of the latitude and longitude coordinates,\r
         * specified in meters.\r
         *\r
         * This will always be a non-negative number.\r
         *\r
         * This corresponds to a 95% confidence level.\r
         * @readonly\r
         */\r
        accuracy: null,\r
\r
        /**\r
         * @cfg {Number} altitude\r
         * Read-only property representing the last retrieved\r
         * height of the position, specified in meters above the ellipsoid\r
         * [WGS84](http://dev.w3.org/geo/api/spec-source.html#ref-wgs).\r
         * @readonly\r
         */\r
        altitude: null,\r
\r
        /**\r
         * @cfg {Number} altitudeAccuracy\r
         * Read-only property representing the last retrieved\r
         * accuracy level of the altitude coordinate, specified in meters.\r
         *\r
         * If altitude is not null then this will be a non-negative number.\r
         * Otherwise this returns `null`.\r
         *\r
         * This corresponds to a 95% confidence level.\r
         * @readonly\r
         */\r
        altitudeAccuracy: null,\r
\r
        /**\r
         * @cfg {Number} heading\r
         * Read-only property representing the last retrieved\r
         * direction of travel of the hosting device,\r
         * specified in non-negative degrees between 0 and 359,\r
         * counting clockwise relative to the true north.\r
         *\r
         * If speed is 0 (device is stationary), then this returns `NaN`.\r
         * @readonly\r
         */\r
        heading: null,\r
\r
        /**\r
         * @cfg {Number} speed\r
         * Read-only property representing the last retrieved\r
         * current ground speed of the device, specified in meters per second.\r
         *\r
         * If this feature is unsupported by the device, this returns `null`.\r
         *\r
         * If the device is stationary, this returns 0,\r
         * otherwise it returns a non-negative number.\r
         * @readonly\r
         */\r
        speed: null,\r
\r
        /**\r
         * @cfg {Date} timestamp\r
         * Read-only property representing when the last retrieved\r
         * positioning information was acquired by the device.\r
         * @readonly\r
         */\r
        timestamp: null,\r
\r
        //PositionOptions interface\r
        /**\r
         * @cfg {Boolean} allowHighAccuracy\r
         * When set to `true`, provide a hint that the application would like to receive\r
         * the best possible results. This may result in slower response times or increased power consumption.\r
         * The user might also deny this capability, or the device might not be able to provide more accurate\r
         * results than if this option was set to `false`.\r
         */\r
        allowHighAccuracy: false,\r
\r
        /**\r
         * @cfg {Number} timeout\r
         * The maximum number of milliseconds allowed to elapse between a location update operation\r
         * and the corresponding {@link #locationupdate} event being raised.  If a location was not successfully\r
         * acquired before the given timeout elapses (and no other internal errors have occurred in this interval),\r
         * then a {@link #locationerror} event will be raised indicating a timeout as the cause.\r
         *\r
         * Note that the time that is spent obtaining the user permission is **not** included in the period\r
         * covered by the timeout.  The `timeout` attribute only applies to the location acquisition operation.\r
         *\r
         * In the case of calling `updateLocation`, the {@link #locationerror} event will be raised only once.\r
         *\r
         * If {@link #autoUpdate} is set to `true`, the {@link #locationerror} event could be raised repeatedly.\r
         * The first timeout is relative to the moment {@link #autoUpdate} was set to `true`\r
         * (or this {@link Ext.util.Geolocation} was initialized with the {@link #autoUpdate} config option set to `true`).\r
         * Subsequent timeouts are relative to the moment when the device determines that it's position has changed.\r
         */\r
        timeout: Infinity,\r
\r
        /**\r
         * @cfg {Number} maximumAge\r
         * This option indicates that the application is willing to accept cached location information whose age\r
         * is no greater than the specified time in milliseconds. If `maximumAge` is set to 0, an attempt to retrieve\r
         * new location information is made immediately.\r
         *\r
         * Setting the `maximumAge` to Infinity returns a cached position regardless of its age.\r
         *\r
         * If the device does not have cached location information available whose age is no\r
         * greater than the specified `maximumAge`, then it must acquire new location information.\r
         *\r
         * For example, if location information no older than 10 minutes is required, set this property to 600000.\r
         */\r
        maximumAge: 0,\r
\r
        /**\r
         * @private\r
         */\r
        provider : undefined\r
    },\r
\r
    updateMaximumAge: function() {\r
        if (this.watchOperation) {\r
            this.updateWatchOperation();\r
        }\r
    },\r
\r
    updateTimeout: function() {\r
        if (this.watchOperation) {\r
            this.updateWatchOperation();\r
        }\r
    },\r
\r
    updateAllowHighAccuracy: function() {\r
        if (this.watchOperation) {\r
            this.updateWatchOperation();\r
        }\r
    },\r
\r
    applyProvider: function(config) {\r
        if (Ext.feature.has.Geolocation) {\r
            if (!config) {\r
                if (navigator && navigator.geolocation) {\r
                    config = navigator.geolocation;\r
                }\r
                else if (window.google) {\r
                    config = google.gears.factory.create('beta.geolocation');\r
                }\r
            }\r
        }\r
        else {\r
            this.fireEvent('locationerror', this, false, false, true, 'This device does not support Geolocation.');\r
        }\r
        return config;\r
    },\r
\r
    updateAutoUpdate: function(newAutoUpdate, oldAutoUpdate) {\r
        var me = this,\r
            provider = me.getProvider();\r
\r
        if (oldAutoUpdate && provider) {\r
            clearInterval(me.watchOperationId);\r
            me.watchOperationId = null;\r
        }\r
\r
        if (newAutoUpdate) {\r
            if (!provider) {\r
                me.fireEvent('locationerror', me, false, false, true, null);\r
                return;\r
            }\r
\r
            try {\r
                me.updateWatchOperation();\r
            }\r
            catch(e) {\r
                me.fireEvent('locationerror', me, false, false, true, e.message);\r
            }\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateWatchOperation: function() {\r
        var me = this,\r
            provider = me.getProvider();\r
\r
        // The native watchPosition method is currently broken in iOS5...\r
\r
        if (me.watchOperationId) {\r
            clearInterval(me.watchOperationId);\r
        }\r
\r
        function pollPosition() {\r
            provider.getCurrentPosition(\r
                Ext.bind(me.fireUpdate, me),\r
                Ext.bind(me.fireError, me),\r
                me.parseOptions()\r
            );\r
        }\r
\r
        pollPosition();\r
        me.watchOperationId = Ext.interval(pollPosition, this.getFrequency());\r
    },\r
\r
    /**\r
     * Executes a onetime location update operation,\r
     * raising either a {@link #locationupdate} or {@link #locationerror} event.\r
     *\r
     * Does not interfere with or restart ongoing location monitoring.\r
     * @param {Function} callback\r
     * A callback method to be called when the location retrieval has been completed.\r
     *\r
     * Will be called on both success and failure.\r
     *\r
     * The method will be passed one parameter, {@link Ext.util.Geolocation}\r
     * (**this** reference), set to `null` on failure.\r
     *\r
     *     geo.updateLocation(function (geo) {\r
     *         alert('Latitude: ' + (geo !== null ? geo.latitude : 'failed'));\r
     *     });\r
     *\r
     * @param {Object} [scope]\r
     * The scope (**this** reference) in which the handler function is executed.\r
     *\r
     * **If omitted, defaults to the object which fired the event.**\r
     *\r
     * <!--positonOptions undocumented param, see W3C spec-->\r
     */\r
    updateLocation: function(callback, scope, positionOptions) {\r
        var me = this,\r
            provider = me.getProvider();\r
\r
        var failFunction = function(message, error) {\r
            if (error) {\r
                me.fireError(error);\r
            }\r
            else {\r
                me.fireEvent('locationerror', me, false, false, true, message);\r
            }\r
            if (callback) {\r
                callback.call(scope || me, null, me); //last parameter for legacy purposes\r
            }\r
        };\r
\r
        if (!provider) {\r
            failFunction(null);\r
            return;\r
        }\r
\r
        try {\r
            provider.getCurrentPosition(\r
                //success callback\r
                function(position) {\r
                    me.fireUpdate(position);\r
                    if (callback) {\r
                        callback.call(scope || me, me, me); //last parameter for legacy purposes\r
                    }\r
                },\r
                //error callback\r
                function(error) {\r
                    failFunction(null, error);\r
                },\r
                positionOptions || me.parseOptions()\r
            );\r
        }\r
        catch(e) {\r
            failFunction(e.message);\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    fireUpdate: function(position) {\r
        var me = this,\r
            coords = position.coords;\r
\r
        this.position = position;\r
\r
        me.setConfig({\r
            timestamp: position.timestamp,\r
            latitude: coords.latitude,\r
            longitude: coords.longitude,\r
            accuracy: coords.accuracy,\r
            altitude: coords.altitude,\r
            altitudeAccuracy: coords.altitudeAccuracy,\r
            heading: coords.heading,\r
            speed: coords.speed\r
        });\r
\r
        me.fireEvent('locationupdate', me);\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    fireError: function(error) {\r
        var errorCode = error.code;\r
        this.fireEvent('locationerror', this,\r
            errorCode == error.TIMEOUT,\r
            errorCode == error.PERMISSION_DENIED,\r
            errorCode == error.POSITION_UNAVAILABLE,\r
            error.message == undefined ? null : error.message\r
        );\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    parseOptions: function() {\r
        var timeout = this.getTimeout(),\r
            ret = {\r
                maximumAge: this.getMaximumAge(),\r
                enableHighAccuracy: this.getAllowHighAccuracy()\r
            };\r
\r
        //Google doesn't like Infinity\r
        if (timeout !== Infinity) {\r
            ret.timeout = timeout;\r
        }\r
        return ret;\r
    },\r
\r
    destroy: function() {\r
        this.setAutoUpdate(false);\r
        this.callParent();\r
    }\r
});\r