diff --git a/src/ol/Collection.js b/src/ol/Collection.js index d57fc2e831..a713fc4851 100644 --- a/src/ol/Collection.js +++ b/src/ol/Collection.js @@ -19,13 +19,13 @@ const Property = { /** * @classdesc - * Events emitted by {@link ol.Collection} instances are instances of this + * Events emitted by {@link module:ol/Collection~Collection} instances are instances of this * type. * * @constructor - * @extends {ol.events.Event} + * @extends {module:ol/events/Event~Event} * @implements {oli.CollectionEvent} - * @param {ol.CollectionEventType} type Type. + * @param {module:ol/CollectionEventType} type Type. * @param {*=} opt_element Element. */ export const CollectionEvent = function(type, opt_element) { @@ -45,10 +45,10 @@ inherits(CollectionEvent, Event); /** - * @typedef {{unique: (boolean|undefined)}} + * @typedef {Object} CollectionOptions + * @property {boolean} [unique=false] Disallow the same item from being added to + * the collection twice. */ -export let CollectionOptions; - /** * @classdesc @@ -59,12 +59,10 @@ export let CollectionOptions; * Collection as a whole. * * @constructor - * @extends {ol.Object} - * @fires ol.CollectionEvent + * @extends {module:ol/Object~Object} + * @fires module:ol/Collection~CollectionEvent * @param {Array.=} opt_array Array. - * @param {CollectionOptions=} opt_options Collection options. - * @param {boolean|undefined} opt_options.unique Disallow the same item from - * being added to the collection twice. Default is false. + * @param {module:ol/Collection~CollectionOptions=} opt_options Collection options. * @template T * @api */ @@ -114,7 +112,7 @@ Collection.prototype.clear = function() { * Add elements to the collection. This pushes each item in the provided array * to the end of the collection. * @param {!Array.} arr Array. - * @return {ol.Collection.} This collection. + * @return {module:ol/Collection~Collection.} This collection. * @api */ Collection.prototype.extend = function(arr) { diff --git a/src/ol/Geolocation.js b/src/ol/Geolocation.js index 4cebf5ea81..2f82079d81 100644 --- a/src/ol/Geolocation.js +++ b/src/ol/Geolocation.js @@ -13,11 +13,14 @@ import {get as getProjection, getTransformFromProjections, identityTransform} fr /** - * @typedef {{tracking: (boolean|undefined), - * trackingOptions: (GeolocationPositionOptions|undefined), - * projection: ol.ProjectionLike}} + * @typedef {Object} GeolocationOptions + * @property {boolean} [tracking=false] Start Tracking right after + * instantiation. + * @property {GeolocationPositionOptions} [trackingOptions] Tracking options. + * See {@link http://www.w3.org/TR/geolocation-API/#position_options_interface}. + * @property {module:ol/types~ProjectionLike} [projection] The projection the position + * is reported in. */ -export let GeolocationOptions; /** @@ -27,11 +30,11 @@ export let GeolocationOptions; * is used to locate a user's position. * * To get notified of position changes, register a listener for the generic - * `change` event on your instance of `ol.Geolocation`. + * `change` event on your instance of {@link module:ol/Geolocation~Geolocation}. * * Example: * - * var geolocation = new ol.Geolocation({ + * var geolocation = new Geolocation({ * // take the projection to use from the map's view * projection: view.getProjection() * }); @@ -42,15 +45,8 @@ export let GeolocationOptions; * * @fires error * @constructor - * @extends {ol.Object} - * @param {GeolocationOptions=} opt_options Options. - * @param {boolean|undefined} opt_options.tracking Start Tracking. Default is - * `false`. - * @param {GeolocationPositionOptions|undefined} opt_options.trackingOptions - * Tracking options. See - * {@link http://www.w3.org/TR/geolocation-API/#position_options_interface}. - * @param {ol.ProjectionLike} opt_options.projection The projection the position - * is reported in. + * @extends {module:ol/Object~Object} + * @param {module:ol/Geolocation~GeolocationOptions=} opt_options Options. * @api */ const Geolocation = function(opt_options) { @@ -62,13 +58,13 @@ const Geolocation = function(opt_options) { /** * The unprojected (EPSG:4326) device position. * @private - * @type {ol.Coordinate} + * @type {module:ol/types~Coordinate} */ this.position_ = null; /** * @private - * @type {ol.TransformFunction} + * @type {module:ol/types~TransformFunction} */ this.transform_ = identityTransform; @@ -203,12 +199,12 @@ Geolocation.prototype.getAccuracy = function() { /** * Get a geometry of the position accuracy. - * @return {?ol.geom.Polygon} A geometry of the position accuracy. + * @return {?module:ol/geom/Polygon~Polygon} A geometry of the position accuracy. * @observable * @api */ Geolocation.prototype.getAccuracyGeometry = function() { - return /** @type {?ol.geom.Polygon} */ (this.get(GeolocationProperty.ACCURACY_GEOMETRY) || null); + return /** @type {?module:ol/geom/Polygon~Polygon} */ (this.get(GeolocationProperty.ACCURACY_GEOMETRY) || null); }; @@ -251,25 +247,25 @@ Geolocation.prototype.getHeading = function() { /** * Get the position of the device. - * @return {ol.Coordinate|undefined} The current position of the device reported + * @return {module:ol/types~Coordinate|undefined} The current position of the device reported * in the current projection. * @observable * @api */ Geolocation.prototype.getPosition = function() { - return /** @type {ol.Coordinate|undefined} */ (this.get(GeolocationProperty.POSITION)); + return /** @type {module:ol/types~Coordinate|undefined} */ (this.get(GeolocationProperty.POSITION)); }; /** * Get the projection associated with the position. - * @return {ol.proj.Projection|undefined} The projection the position is + * @return {module:ol/proj/Projection~Projection|undefined} The projection the position is * reported in. * @observable * @api */ Geolocation.prototype.getProjection = function() { - return /** @type {ol.proj.Projection|undefined} */ (this.get(GeolocationProperty.PROJECTION)); + return /** @type {module:ol/proj/Projection~Projection|undefined} */ (this.get(GeolocationProperty.PROJECTION)); }; @@ -312,7 +308,7 @@ Geolocation.prototype.getTrackingOptions = function() { /** * Set the projection to use for transforming the coordinates. - * @param {ol.ProjectionLike} projection The projection the position is + * @param {module:ol/types~ProjectionLike} projection The projection the position is * reported in. * @observable * @api diff --git a/src/ol/Graticule.js b/src/ol/Graticule.js index 9dc8c5eda0..abb4c37c9b 100644 --- a/src/ol/Graticule.js +++ b/src/ol/Graticule.js @@ -17,7 +17,7 @@ import Text from './style/Text.js'; /** - * @type {ol.style.Stroke} + * @type {module:ol/style/Stroke~Stroke} * @private * @const */ @@ -34,109 +34,101 @@ const INTERVALS = [ 90, 45, 30, 20, 10, 5, 2, 1, 0.5, 0.2, 0.1, 0.05, 0.01, 0.005, 0.002, 0.001 ]; +/** + * @typedef {Object} GraticuleLabelDataType + * @property {module:ol/geom/Point~Point} geom + * @property {string} text + */ /** - * @typedef {{map: (ol.PluggableMap|undefined), - * maxLines: (number|undefined), - * strokeStyle: (ol.style.Stroke|undefined), - * targetSize: (number|undefined), - * showLabels: (boolean|undefined), - * lonLabelFormatter: (undefined|function(number):string), - * latLabelFormatter: (undefined|function(number):string), - * lonLabelPosition: (number|undefined), - * latLabelPosition: (number|undefined), - * lonLabelStyle: (ol.style.Text|undefined), - * latLabelStyle: (ol.style.Text|undefined)}} + * @typedef {Object} GraticuleOptions + * @property {module:ol/PluggableMap~PluggableMap} [map] Reference to an + * {@link module:ol/Map~Map} object. + * @property {number} [maxLines=100] The maximum number of meridians and + * parallels from the center of the map. The default value of 100 means that at + * most 200 meridians and 200 parallels will be displayed. The default value is + * appropriate for conformal projections like Spherical Mercator. If you + * increase the value, more lines will be drawn and the drawing performance will + * decrease. + * @property {module:ol/style/Stroke~Stroke} [strokeStyle='rgba(0,0,0,0.2)'] The + * stroke style to use for drawing the graticule. If not provided, a not fully + * opaque black will be used. + * @property {number} [targetSize=100] The target size of the graticule cells, + * in pixels. + * @property {boolean} [showLabels=false] Render a label with the respective + * latitude/longitude for each graticule line. + * @property {function(number):string} [lonLabelFormatter] Label formatter for + * longitudes. This function is called with the longitude as argument, and + * should return a formatted string representing the longitude. By default, + * labels are formatted as degrees, minutes, seconds and hemisphere. + * @property {number} [lonLabelPosition=0] Longitude label position in fractions + * (0..1) of view extent. 0 means at the bottom of the viewport, 1 means at the + * top. + * @property {number} [latLabelPosition=1] Latitude label position in fractions + * (0..1) of view extent. 0 means at the left of the viewport, 1 means at the + * right. + * @property {module:ol/style/Text~Text} [lonLabelStyle] Longitude label text + * style. If not provided, the following style will be used: + * ```js + * new Text({ + * font: '12px Calibri,sans-serif', + * textBaseline: 'bottom', + * fill: new Fill({ + * color: 'rgba(0,0,0,1)' + * }), + * stroke: new Stroke({ + * color: 'rgba(255,255,255,1)', + * width: 3 + * }) + * }); + * ``` + * Note that the default's `textBaseline` configuration will not work well for + * `lonLabelPosition` configurations that position labels close to the top of + * the viewport. + * @param {module:ol/style/Text~Text} [latLabelStyle] Latitude label text style. + * If not provided, the following style will be used: + * ```js + * new Text({ + * font: '12px Calibri,sans-serif', + * textAlign: 'end', + * fill: new Fill({ + * color: 'rgba(0,0,0,1)' + * }), + * stroke: Stroke({ + * color: 'rgba(255,255,255,1)', + * width: 3 + * }) + * }); + * ``` + * Note that the default's `textAlign` configuration will not work well for + * `latLabelPosition` configurations that position labels close to the left of + * the viewport. */ -export let GraticuleOptions; /** * Render a grid for a coordinate system on a map. * @constructor - * @param {GraticuleOptions=} opt_options Options. - * @param {ol.PluggableMap|undefined} opt_options.map Reference to an `ol.Map` - * object. - * @param {number|undefined} opt_options.maxLines The maximum number of - * meridians and parallels from the center of the - * map. The default value is 100, which means that at most 200 meridians - * and 200 parallels will be displayed. The default value is appropriate - * for conformal projections like Spherical Mercator. If you increase - * the value more lines will be drawn and the drawing performance will - * decrease. - * @param {ol.style.Stroke|undefined} opt_options.strokeStyle The stroke style - * to use for drawing the graticule. If not provided, the - * lines will be drawn with `rgba(0,0,0,0.2)`, a not fully opaque black. - * @param {number|undefined} opt_options.targetSize The target size of the - * graticule cells, in pixels. Default value is 100 pixels. - * @param {boolean|undefined} opt_options.showLabels Render a label with the - * respective latitude/longitude for each graticule line. Default is false. - * @param {undefined|function(number):string} opt_options.lonLabelFormatter - * Label formatter for longitudes. This function is called with the - * longitude as argument, and should return a formatted string representing - * the longitude. By default, labels are formatted as degrees, minutes, - * seconds and hemisphere. - * @param {number|undefined} opt_options.lonLabelPosition Longitude label - * position in fractions (0..1) of view extent. 0 means at the bottom of the - * viewport, 1 means at the top. Default is 0. - * @param {number|undefined} opt_options.latLabelPosition Latitude label - * position in fractions (0..1) of view extent. 0 means at the left of the - * viewport, 1 means at the right. Default is 1. - * @param {ol.style.Text|undefined} options.lonLabelStyle Longitude label text - * style. The default is - * ```js - * new ol.style.Text({ - * font: '12px Calibri,sans-serif', - * textBaseline: 'bottom', - * fill: new ol.style.Fill({ - * color: 'rgba(0,0,0,1)' - * }), - * stroke: new ol.style.Stroke({ - * color: 'rgba(255,255,255,1)', - * width: 3 - * }) - * }); - * ``` - * Note that the default's `textBaseline` configuration will not work well - * for `lonLabelPosition` configurations that position labels close to the - * top of the viewport. - * @param {ol.style.Text|undefined} opt_options.latLabelStyle Latitude label - * text style. The default is - * ```js - * new ol.style.Text({ - * font: '12px Calibri,sans-serif', - * textAlign: 'end', - * fill: new ol.style.Fill({ - * color: 'rgba(0,0,0,1)' - * }), - * stroke: new ol.style.Stroke({ - * color: 'rgba(255,255,255,1)', - * width: 3 - * }) - * }); - * ``` - * Note that the default's `textAlign` configuration will not work well for - * `latLabelPosition` configurations that position labels close to the left - * of the viewport. + * @param {module:ol/Graticule~GraticuleOptions=} opt_options Options. * @api */ const Graticule = function(opt_options) { const options = opt_options || {}; /** - * @type {ol.PluggableMap} + * @type {module:ol/PluggableMap~PluggableMap} * @private */ this.map_ = null; /** - * @type {?ol.EventsKey} + * @type {?module:ol/types~EventsKey} * @private */ this.postcomposeListenerKey_ = null; /** - * @type {ol.proj.Projection} + * @type {module:ol/proj/Projection~Projection} */ this.projection_ = null; @@ -201,49 +193,49 @@ const Graticule = function(opt_options) { this.maxLines_ = options.maxLines !== undefined ? options.maxLines : 100; /** - * @type {Array.} + * @type {Array.} * @private */ this.meridians_ = []; /** - * @type {Array.} + * @type {Array.} * @private */ this.parallels_ = []; /** - * @type {ol.style.Stroke} + * @type {module:ol/style/Stroke~Stroke} * @private */ this.strokeStyle_ = options.strokeStyle !== undefined ? options.strokeStyle : DEFAULT_STROKE_STYLE; /** - * @type {ol.TransformFunction|undefined} + * @type {module:ol/types~TransformFunction|undefined} * @private */ this.fromLonLatTransform_ = undefined; /** - * @type {ol.TransformFunction|undefined} + * @type {module:ol/types~TransformFunction|undefined} * @private */ this.toLonLatTransform_ = undefined; /** - * @type {ol.Coordinate} + * @type {module:ol/types~Coordinate} * @private */ this.projectionCenterLonLat_ = null; /** - * @type {Array.} + * @type {Array.} * @private */ this.meridiansLabels_ = null; /** - * @type {Array.} + * @type {Array.} * @private */ this.parallelsLabels_ = null; @@ -284,7 +276,7 @@ const Graticule = function(opt_options) { options.latLabelPosition; /** - * @type {ol.style.Text} + * @type {module:ol/style/Text~Text} * @private */ this.lonLabelStyle_ = options.lonLabelStyle !== undefined ? options.lonLabelStyle : @@ -301,7 +293,7 @@ const Graticule = function(opt_options) { }); /** - * @type {ol.style.Text} + * @type {module:ol/style/Text~Text} * @private */ this.latLabelStyle_ = options.latLabelStyle !== undefined ? options.latLabelStyle : @@ -330,7 +322,7 @@ const Graticule = function(opt_options) { * @param {number} minLat Minimal latitude. * @param {number} maxLat Maximal latitude. * @param {number} squaredTolerance Squared tolerance. - * @param {ol.Extent} extent Extent. + * @param {module:ol/types~Extent} extent Extent. * @param {number} index Index. * @return {number} Index. * @private @@ -351,10 +343,10 @@ Graticule.prototype.addMeridian_ = function(lon, minLat, maxLat, squaredToleranc }; /** - * @param {ol.geom.LineString} lineString Meridian - * @param {ol.Extent} extent Extent. + * @param {module:ol/geom/LineString~LineString} lineString Meridian + * @param {module:ol/types~Extent} extent Extent. * @param {number} index Index. - * @return {ol.geom.Point} Meridian point. + * @return {module:ol/geom/Point~Point} Meridian point. * @private */ Graticule.prototype.getMeridianPoint_ = function(lineString, extent, index) { @@ -377,7 +369,7 @@ Graticule.prototype.getMeridianPoint_ = function(lineString, extent, index) { * @param {number} minLon Minimal longitude. * @param {number} maxLon Maximal longitude. * @param {number} squaredTolerance Squared tolerance. - * @param {ol.Extent} extent Extent. + * @param {module:ol/types~Extent} extent Extent. * @param {number} index Index. * @return {number} Index. * @private @@ -399,10 +391,10 @@ Graticule.prototype.addParallel_ = function(lat, minLon, maxLon, squaredToleranc /** - * @param {ol.geom.LineString} lineString Parallels. - * @param {ol.Extent} extent Extent. + * @param {module:ol/geom/LineString~LineString} lineString Parallels. + * @param {module:ol/types~Extent} extent Extent. * @param {number} index Index. - * @return {ol.geom.Point} Parallel point. + * @return {module:ol/geom/Point~Point} Parallel point. * @private */ Graticule.prototype.getParallelPoint_ = function(lineString, extent, index) { @@ -421,8 +413,8 @@ Graticule.prototype.getParallelPoint_ = function(lineString, extent, index) { /** - * @param {ol.Extent} extent Extent. - * @param {ol.Coordinate} center Center. + * @param {module:ol/types~Extent} extent Extent. + * @param {module:ol/types~Coordinate} center Center. * @param {number} resolution Resolution. * @param {number} squaredTolerance Squared tolerance. * @private @@ -550,7 +542,7 @@ Graticule.prototype.getInterval_ = function(resolution) { /** * Get the map associated with this graticule. - * @return {ol.PluggableMap} The map. + * @return {module:ol/PluggableMap~PluggableMap} The map. * @api */ Graticule.prototype.getMap = function() { @@ -563,7 +555,7 @@ Graticule.prototype.getMap = function() { * @param {number} minLat Minimal latitude. * @param {number} maxLat Maximal latitude. * @param {number} squaredTolerance Squared tolerance. - * @return {ol.geom.LineString} The meridian line string. + * @return {module:ol/geom/LineString~LineString} The meridian line string. * @param {number} index Index. * @private */ @@ -577,7 +569,7 @@ Graticule.prototype.getMeridian_ = function(lon, minLat, maxLat, squaredToleranc /** * Get the list of meridians. Meridians are lines of equal longitude. - * @return {Array.} The meridians. + * @return {Array.} The meridians. * @api */ Graticule.prototype.getMeridians = function() { @@ -590,7 +582,7 @@ Graticule.prototype.getMeridians = function() { * @param {number} minLon Minimal longitude. * @param {number} maxLon Maximal longitude. * @param {number} squaredTolerance Squared tolerance. - * @return {ol.geom.LineString} The parallel line string. + * @return {module:ol/geom/LineString~LineString} The parallel line string. * @param {number} index Index. * @private */ @@ -604,7 +596,7 @@ Graticule.prototype.getParallel_ = function(lat, minLon, maxLon, squaredToleranc /** * Get the list of parallels. Parallels are lines of equal latitude. - * @return {Array.} The parallels. + * @return {Array.} The parallels. * @api */ Graticule.prototype.getParallels = function() { @@ -613,7 +605,7 @@ Graticule.prototype.getParallels = function() { /** - * @param {ol.render.Event} e Event. + * @param {module:ol/render/Event~Event} e Event. * @private */ Graticule.prototype.handlePostCompose_ = function(e) { @@ -669,7 +661,7 @@ Graticule.prototype.handlePostCompose_ = function(e) { /** - * @param {ol.proj.Projection} projection Projection. + * @param {module:ol/proj/Projection~Projection} projection Projection. * @private */ Graticule.prototype.updateProjectionInfo_ = function(projection) { @@ -713,7 +705,7 @@ Graticule.prototype.updateProjectionInfo_ = function(projection) { /** * Set the map for this graticule. The graticule will be rendered on the * provided map. - * @param {ol.PluggableMap} map Map. + * @param {module:ol/PluggableMap~PluggableMap} map Map. * @api */ Graticule.prototype.setMap = function(map) { diff --git a/src/ol/PluggableMap.js b/src/ol/PluggableMap.js index ed8d18f7c9..9232f5cb7d 100644 --- a/src/ol/PluggableMap.js +++ b/src/ol/PluggableMap.js @@ -32,83 +32,78 @@ import {create as createTransform, apply as applyTransform} from './transform.js /** - * Object literal with config options for the map. - * @typedef {{controls: (ol.Collection.|Array.|undefined), - * pixelRatio: (number|undefined), - * interactions: (ol.Collection.|Array.|undefined), - * keyboardEventTarget: (Element|Document|string|undefined), - * layers: (Array.|ol.Collection.|undefined), - * loadTilesWhileAnimating: (boolean|undefined), - * loadTilesWhileInteracting: (boolean|undefined), - * moveTolerance: (number|undefined), - * overlays: (ol.Collection.|Array.|undefined), - * renderer: (ol.renderer.Type|Array.|undefined), - * target: (Element|string|undefined), - * view: (ol.View|undefined)}} + * @typedef {Object} MapOptionsInternal + * @property {module:ol/Collection~Collection.} [controls] + * @property {module:ol/Collection~Collection.} [interactions] + * @property {Element|Document} keyboardEventTarget + * @property {module:ol/Collection~Collection.} overlays + * @property {olx.MapRendererPlugin} mapRendererPlugin + * @property {Object.} values + */ + + +/** + * Object literal with config options for the map. + * @typedef {Object} MapOptions + * @property {module:ol/Collection~Collectiion.|Array.} [controls] + * Controls initially added to the map. If not specified, + * {@link module:ol/control~defaults} is used. + * @property {number} [pixelRatio=window.devicePixelRatio] The ratio between + * physical pixels and device-independent pixels (dips) on the device. + * @property {module:ol/Collection~Collection.|Array.} [interactions] + * Interactions that are initially added to the map. If not specified, + * {@link module:ol/interaction~defaults} is used. + * @property {Element|Document|string} [keyboardEventTarget] The element to + * listen to keyboard events on. This determines when the `KeyboardPan` and + * `KeyboardZoom` interactions trigger. For example, if this option is set to + * `document` the keyboard interactions will always trigger. If this option is + * not specified, the element the library listens to keyboard events on is the + * map target (i.e. the user-provided div for the map). If this is not + * `document`, the target element needs to be focused for key events to be + * emitted, requiring that the target element has a `tabindex` attribute. + * @property {Array.|module:ol/Collection.} [layers] + * Layers. If this is not defined, a map with no layers will be rendered. Note + * that layers are rendered in the order supplied, so if you want, for example, + * a vector layer to appear on top of a tile layer, it must come after the tile + * layer. + * @property {number} [maxTilesLoading=16] Maximum number tiles to load + * simultaneously. + * @property {boolean} [loadTilesWhileAnimating=false] When set to `true`, tiles + * will be loaded during animations. This may improve the user experience, but + * can also make animations stutter on devices with slow memory. + * @property {boolean} [loadTilesWhileInteracting=false] When set to `true`, + * tiles will be loaded while interacting with the map. This may improve the + * user experience, but can also make map panning and zooming choppy on devices + * with slow memory. + * @property {number} [moveTolerance=1] The minimum distance in pixels the + * cursor must move to be detected as a map move event instead of a click. + * Increasing this value can make it easier to click on the map. + * @property {module:ol/Collection~Collection.|Array.} [overlays] + * Overlays initially added to the map. By default, no overlays are added. + * @property {module:ol/renderer/Type|Array.} [renderer] + * Renderer. By default, Canvas and WebGL renderers are tested for support in + * that order, and the first supported used. Specify a + * {@link module:ol/renderer/Type} here to use a specific renderer. Note that + * the Canvas renderer fully supports vector data, but WebGL can only render + * Point geometries reliably. + * @property {Element|string} [target] The container for the map, either the + * element itself or the `id` of the element. If not specified at construction + * time, {@link module:ol/Map~Map#setTarget} must be called for the map to be + * rendered. + * @property {module:ol/View} [view] The map's view. No layer sources will be + * fetched unless this is specified at construction time or through + * {@link module:ol/Map~Map#setView}. */ -export let MapOptions; /** * @constructor - * @extends {ol.Object} - * @param {MapOptions} options Map options. - * @param {ol.Collection.|Array.|undefined} options.controls - * Controls initially added to the map. If not specified, - * {@link ol.control.defaults ol.control.defaults()} is used. - * @param {number|undefined} options.pixelRatio The ratio between physical - * pixels and device-independent pixels (dips) on the device. If - * `undefined` then it gets set by using `window.devicePixelRatio`. - * @param {ol.Collection.|Array.|undefined} options.interactions - * Interactions that are initially added to the map. If not specified, - * {@link ol.interaction.defaults ol.interaction.defaults()} is used. - * @param {Element|Document|string|undefined} options.keyboardEventTarget The - * element to listen to keyboard events on. This determines when the - * `KeyboardPan` and `KeyboardZoom` interactions trigger. For example, if - * this option is set to `document` the keyboard interactions will always - * trigger. If this option is not specified, the element the library listens - * to keyboard events on is the map target (i.e. the user-provided div for - * the map). If this is not `document` the target element needs to be - * focused for key events to be emitted, requiring that the target element - * has a `tabindex` attribute. - * @param {Array.|ol.Collection.|undefined} options.layers - * Layers. If this is not defined, a map with no layers will be rendered. - * Note that layers are rendered in the order supplied, so if you want, for - * example, a vector layer to appear on top of a tile layer, it must come - * after the tile layer. - * @param {number|undefined} options.maxTilesLoading Maximum number tiles to load - * simultaneously. Default is `16`. - * @param {boolean|undefined} options.loadTilesWhileAnimating When set to true, - * tiles will be loaded during animations. This may improve the user - * experience, but can also make animations stutter on devices with slow - * memory. Default is `false`. - * @param {boolean|undefined} options.loadTilesWhileInteracting When set to - * true, tiles will be loaded while interacting with the map. This may - * improve the user experience, but can also make map panning and zooming - * choppy on devices with slow memory. Default is `false`. - * @param {number|undefined} options.moveTolerance The minimum distance in - * pixels the cursor must move to be detected as a map move event instead - * of a click. Increasing this value can make it easier to click on the map. - * Default is `1`. - * @param {ol.Collection.|Array.|undefined} options.overlays - * Overlays initially added to the map. By default, no overlays are added. - * @param {ol.renderer.Type|Array.|undefined} options.renderer - * Renderer. By default, Canvas and WebGL renderers are tested for support - * in that order, and the first supported used. Specify a - * {@link ol.renderer.Type} here to use a specific renderer. Note that the - * Canvas renderer fully supports vector data, but WebGL can only render - * Point geometries. - * @param {Element|string|undefined} options.target The container for the map, - * either the element itself or the `id` of the element. If not specified at - * construction time, {@link ol.Map#setTarget} must be called for the map to - * be rendered. - * @param {ol.View|undefined} options.view The map's view. No layer sources - * will be fetched unless this is specified at construction time or through - * {@link ol.Map#setView}. - * @fires ol.MapBrowserEvent - * @fires ol.MapEvent - * @fires ol.render.Event#postcompose - * @fires ol.render.Event#precompose + * @extends {module:ol/Object~Object} + * @param {module:ol/PluggableMap~MapOptions} options Map options. + * @fires module:ol/MapBrowserEvent~MapBrowserEvent + * @fires module:ol/MapEvent~MapEvent + * @fires module:ol/render/Event~Event#postcompose + * @fires module:ol/render/Event~Event#precompose * @api */ const PluggableMap = function(options) { @@ -162,13 +157,13 @@ const PluggableMap = function(options) { /** * @private - * @type {ol.Transform} + * @type {module:ol/types~Transform} */ this.coordinateToPixelTransform_ = createTransform(); /** * @private - * @type {ol.Transform} + * @type {module:ol/types~Transform} */ this.pixelToCoordinateTransform_ = createTransform(); @@ -187,25 +182,25 @@ const PluggableMap = function(options) { /** * The extent at the previous 'moveend' event. * @private - * @type {ol.Extent} + * @type {module:ol/types~Extent} */ this.previousExtent_ = null; /** * @private - * @type {?ol.EventsKey} + * @type {?module:ol/types~EventsKey} */ this.viewPropertyListenerKey_ = null; /** * @private - * @type {?ol.EventsKey} + * @type {?module:ol/types~EventsKey} */ this.viewChangeListenerKey_ = null; /** * @private - * @type {Array.} + * @type {Array.} */ this.layerGroupPropertyListenerKeys_ = null; @@ -254,7 +249,7 @@ const PluggableMap = function(options) { /** * @private - * @type {ol.MapBrowserEventHandler} + * @type {module:ol/MapBrowserEventHandler~MapBrowserEventHandler} */ this.mapBrowserEventHandler_ = new MapBrowserEventHandler(this, options.moveTolerance); for (const key in MapBrowserEventType) { @@ -270,7 +265,7 @@ const PluggableMap = function(options) { /** * @private - * @type {Array.} + * @type {Array.} */ this.keyHandlerKeys_ = null; @@ -282,19 +277,19 @@ const PluggableMap = function(options) { this.handleBrowserEvent, this); /** - * @type {ol.Collection.} + * @type {module:ol/Collection~Collection.} * @protected */ this.controls = optionsInternal.controls || new Collection(); /** - * @type {ol.Collection.} + * @type {module:ol/Collection~Collection.} * @protected */ this.interactions = optionsInternal.interactions || new Collection(); /** - * @type {ol.Collection.} + * @type {module:ol/Collection~Collection.} * @private */ this.overlays_ = optionsInternal.overlays; @@ -302,12 +297,12 @@ const PluggableMap = function(options) { /** * A lookup of overlays by id. * @private - * @type {Object.} + * @type {Object.} */ this.overlayIdIndex_ = {}; /** - * @type {ol.renderer.Map} + * @type {module:ol/renderer/Map~Map} * @private */ this.renderer_ = optionsInternal.mapRendererPlugin['create'](this.viewport_, this); @@ -320,19 +315,19 @@ const PluggableMap = function(options) { /** * @private - * @type {ol.Coordinate} + * @type {module:ol/types~Coordinate} */ this.focus_ = null; /** * @private - * @type {Array.} + * @type {Array.} */ this.postRenderFunctions_ = []; /** * @private - * @type {ol.TileQueue} + * @type {module:ol/TileQueue~TileQueue} */ this.tileQueue_ = new TileQueue( this.getTilePriority.bind(this), @@ -361,8 +356,8 @@ const PluggableMap = function(options) { this.controls.forEach( /** - * @param {ol.control.Control} control Control. - * @this {ol.PluggableMap} + * @param {module:ol/control/Control~Control} control Control. + * @this {module:ol/PluggableMap~PluggableMap} */ function(control) { control.setMap(this); @@ -370,7 +365,7 @@ const PluggableMap = function(options) { listen(this.controls, CollectionEventType.ADD, /** - * @param {ol.CollectionEvent} event CollectionEvent. + * @param {module:ol/Collection~CollectionEvent} event CollectionEvent. */ function(event) { event.element.setMap(this); @@ -378,7 +373,7 @@ const PluggableMap = function(options) { listen(this.controls, CollectionEventType.REMOVE, /** - * @param {ol.CollectionEvent} event CollectionEvent. + * @param {module:ol/Collection~CollectionEvent} event CollectionEvent. */ function(event) { event.element.setMap(null); @@ -386,8 +381,8 @@ const PluggableMap = function(options) { this.interactions.forEach( /** - * @param {ol.interaction.Interaction} interaction Interaction. - * @this {ol.PluggableMap} + * @param {module:ol/interaction/Interaction~Interaction} interaction Interaction. + * @this {module:ol/PluggableMap~PluggableMap} */ function(interaction) { interaction.setMap(this); @@ -395,7 +390,7 @@ const PluggableMap = function(options) { listen(this.interactions, CollectionEventType.ADD, /** - * @param {ol.CollectionEvent} event CollectionEvent. + * @param {module:ol/Collection~CollectionEvent} event CollectionEvent. */ function(event) { event.element.setMap(this); @@ -403,7 +398,7 @@ const PluggableMap = function(options) { listen(this.interactions, CollectionEventType.REMOVE, /** - * @param {ol.CollectionEvent} event CollectionEvent. + * @param {module:ol/Collection~CollectionEvent} event CollectionEvent. */ function(event) { event.element.setMap(null); @@ -413,18 +408,18 @@ const PluggableMap = function(options) { listen(this.overlays_, CollectionEventType.ADD, /** - * @param {ol.CollectionEvent} event CollectionEvent. + * @param {module:ol/Collection~CollectionEvent} event CollectionEvent. */ function(event) { - this.addOverlayInternal_(/** @type {ol.Overlay} */ (event.element)); + this.addOverlayInternal_(/** @type {module:ol/Overlay~Overlay} */ (event.element)); }, this); listen(this.overlays_, CollectionEventType.REMOVE, /** - * @param {ol.CollectionEvent} event CollectionEvent. + * @param {module:ol/Collection~CollectionEvent} event CollectionEvent. */ function(event) { - const overlay = /** @type {ol.Overlay} */ (event.element); + const overlay = /** @type {module:ol/Overlay~Overlay} */ (event.element); const id = overlay.getId(); if (id !== undefined) { delete this.overlayIdIndex_[id.toString()]; @@ -439,7 +434,7 @@ inherits(PluggableMap, BaseObject); /** * Add the given control to the map. - * @param {ol.control.Control} control Control. + * @param {module:ol/control/Control~Control} control Control. * @api */ PluggableMap.prototype.addControl = function(control) { @@ -449,7 +444,7 @@ PluggableMap.prototype.addControl = function(control) { /** * Add the given interaction to the map. - * @param {ol.interaction.Interaction} interaction Interaction to add. + * @param {module:ol/interaction/Interaction~Interaction} interaction Interaction to add. * @api */ PluggableMap.prototype.addInteraction = function(interaction) { @@ -460,8 +455,8 @@ PluggableMap.prototype.addInteraction = function(interaction) { /** * Adds the given layer to the top of this map. If you want to add a layer * elsewhere in the stack, use `getLayers()` and the methods available on - * {@link ol.Collection}. - * @param {ol.layer.Base} layer Layer. + * {@link module:ol/Collection~Collection}. + * @param {module:ol/layer/Base~Base} layer Layer. * @api */ PluggableMap.prototype.addLayer = function(layer) { @@ -472,7 +467,7 @@ PluggableMap.prototype.addLayer = function(layer) { /** * Add the given overlay to the map. - * @param {ol.Overlay} overlay Overlay. + * @param {module:ol/Overlay~Overlay} overlay Overlay. * @api */ PluggableMap.prototype.addOverlay = function(overlay) { @@ -482,7 +477,7 @@ PluggableMap.prototype.addOverlay = function(overlay) { /** * This deals with map's overlay collection changes. - * @param {ol.Overlay} overlay Overlay. + * @param {module:ol/Overlay~Overlay} overlay Overlay. * @private */ PluggableMap.prototype.addOverlayInternal_ = function(overlay) { @@ -520,13 +515,13 @@ PluggableMap.prototype.disposeInternal = function() { * Detect features that intersect a pixel on the viewport, and execute a * callback with each intersecting feature. Layers included in the detection can * be configured through the `layerFilter` option in `opt_options`. - * @param {ol.Pixel} pixel Pixel. - * @param {function(this: S, (ol.Feature|ol.render.Feature), - * ol.layer.Layer): T} callback Feature callback. The callback will be + * @param {module:ol/types~Pixel} pixel Pixel. + * @param {function(this: S, (module:ol/Feature~Feature|module:ol/render/Feature~Feature), + * module:ol/layer/Layer~Layer): T} callback Feature callback. The callback will be * called with two arguments. The first argument is one - * {@link ol.Feature feature} or - * {@link ol.render.Feature render feature} at the pixel, the second is - * the {@link ol.layer.Layer layer} of the feature and will be null for + * {@link module:ol/Feature~Feature feature} or + * {@link module:ol/render/Feature~Feature render feature} at the pixel, the second is + * the {@link module:ol/layer/Layer~Layer layer} of the feature and will be null for * unmanaged layers. To stop detection, callback functions can return a * truthy value. * @param {olx.AtPixelOptions=} opt_options Optional options. @@ -553,9 +548,9 @@ PluggableMap.prototype.forEachFeatureAtPixel = function(pixel, callback, opt_opt /** * Get all features that intersect a pixel on the viewport. - * @param {ol.Pixel} pixel Pixel. + * @param {module:ol/types~Pixel} pixel Pixel. * @param {olx.AtPixelOptions=} opt_options Optional options. - * @return {Array.} The detected features or + * @return {Array.} The detected features or * `null` if none were found. * @api */ @@ -574,17 +569,17 @@ PluggableMap.prototype.getFeaturesAtPixel = function(pixel, opt_options) { * Detect layers that have a color value at a pixel on the viewport, and * execute a callback with each matching layer. Layers included in the * detection can be configured through `opt_layerFilter`. - * @param {ol.Pixel} pixel Pixel. - * @param {function(this: S, ol.layer.Layer, (Uint8ClampedArray|Uint8Array)): T} callback + * @param {module:ol/types~Pixel} pixel Pixel. + * @param {function(this: S, module:ol/layer/Layer~Layer, (Uint8ClampedArray|Uint8Array)): T} callback * Layer callback. This callback will receive two arguments: first is the - * {@link ol.layer.Layer layer}, second argument is an array representing + * {@link module:ol/layer/Layer~Layer layer}, second argument is an array representing * [R, G, B, A] pixel values (0 - 255) and will be `null` for layer types * that do not currently support this argument. To stop detection, callback * functions can return a truthy value. * @param {S=} opt_this Value to use as `this` when executing `callback`. - * @param {(function(this: U, ol.layer.Layer): boolean)=} opt_layerFilter Layer + * @param {(function(this: U, module:ol/layer/Layer~Layer): boolean)=} opt_layerFilter Layer * filter function. The filter function will receive one argument, the - * {@link ol.layer.Layer layer-candidate} and it should return a boolean + * {@link module:ol/layer/Layer~Layer layer-candidate} and it should return a boolean * value. Only layers which are visible and for which this function returns * `true` will be tested for features. By default, all visible layers will * be tested. @@ -610,7 +605,7 @@ PluggableMap.prototype.forEachLayerAtPixel = function(pixel, callback, opt_this, /** * Detect if features intersect a pixel on the viewport. Layers included in the * detection can be configured through `opt_layerFilter`. - * @param {ol.Pixel} pixel Pixel. + * @param {module:ol/types~Pixel} pixel Pixel. * @param {olx.AtPixelOptions=} opt_options Optional options. * @return {boolean} Is there a feature at the given pixel? * @template U @@ -633,7 +628,7 @@ PluggableMap.prototype.hasFeatureAtPixel = function(pixel, opt_options) { /** * Returns the coordinate in view projection for a browser event. * @param {Event} event Event. - * @return {ol.Coordinate} Coordinate. + * @return {module:ol/types~Coordinate} Coordinate. * @api */ PluggableMap.prototype.getEventCoordinate = function(event) { @@ -644,7 +639,7 @@ PluggableMap.prototype.getEventCoordinate = function(event) { /** * Returns the map pixel position for a browser event relative to the viewport. * @param {Event} event Event. - * @return {ol.Pixel} Pixel. + * @return {module:ol/types~Pixel} Pixel. * @api */ PluggableMap.prototype.getEventPixel = function(event) { @@ -691,8 +686,8 @@ PluggableMap.prototype.getTargetElement = function() { /** * Get the coordinate for a given pixel. This returns a coordinate in the * map view projection. - * @param {ol.Pixel} pixel Pixel position in the map viewport. - * @return {ol.Coordinate} The coordinate for the pixel position. + * @param {module:ol/types~Pixel} pixel Pixel position in the map viewport. + * @return {module:ol/types~Coordinate} The coordinate for the pixel position. * @api */ PluggableMap.prototype.getCoordinateFromPixel = function(pixel) { @@ -708,7 +703,7 @@ PluggableMap.prototype.getCoordinateFromPixel = function(pixel) { /** * Get the map controls. Modifying this collection changes the controls * associated with the map. - * @return {ol.Collection.} Controls. + * @return {module:ol/Collection~Collection.} Controls. * @api */ PluggableMap.prototype.getControls = function() { @@ -719,7 +714,7 @@ PluggableMap.prototype.getControls = function() { /** * Get the map overlays. Modifying this collection changes the overlays * associated with the map. - * @return {ol.Collection.} Overlays. + * @return {module:ol/Collection~Collection.} Overlays. * @api */ PluggableMap.prototype.getOverlays = function() { @@ -732,7 +727,7 @@ PluggableMap.prototype.getOverlays = function() { * Note that the index treats string and numeric identifiers as the same. So * `map.getOverlayById(2)` will return an overlay with id `'2'` or `2`. * @param {string|number} id Overlay identifier. - * @return {ol.Overlay} Overlay. + * @return {module:ol/Overlay~Overlay} Overlay. * @api */ PluggableMap.prototype.getOverlayById = function(id) { @@ -746,7 +741,7 @@ PluggableMap.prototype.getOverlayById = function(id) { * associated with the map. * * Interactions are used for e.g. pan, zoom and rotate. - * @return {ol.Collection.} Interactions. + * @return {module:ol/Collection~Collection.} Interactions. * @api */ PluggableMap.prototype.getInteractions = function() { @@ -756,18 +751,18 @@ PluggableMap.prototype.getInteractions = function() { /** * Get the layergroup associated with this map. - * @return {ol.layer.Group} A layer group containing the layers in this map. + * @return {module:ol/layer/Group~Group} A layer group containing the layers in this map. * @observable * @api */ PluggableMap.prototype.getLayerGroup = function() { - return /** @type {ol.layer.Group} */ (this.get(MapProperty.LAYERGROUP)); + return /** @type {module:ol/layer/Group~Group} */ (this.get(MapProperty.LAYERGROUP)); }; /** * Get the collection of layers associated with this map. - * @return {!ol.Collection.} Layers. + * @return {!module:ol/Collection~Collection.} Layers. * @api */ PluggableMap.prototype.getLayers = function() { @@ -779,8 +774,8 @@ PluggableMap.prototype.getLayers = function() { /** * Get the pixel for a coordinate. This takes a coordinate in the map view * projection and returns the corresponding pixel. - * @param {ol.Coordinate} coordinate A map coordinate. - * @return {ol.Pixel} A pixel position in the map viewport. + * @param {module:ol/types~Coordinate} coordinate A map coordinate. + * @return {module:ol/types~Pixel} A pixel position in the map viewport. * @api */ PluggableMap.prototype.getPixelFromCoordinate = function(coordinate) { @@ -795,7 +790,7 @@ PluggableMap.prototype.getPixelFromCoordinate = function(coordinate) { /** * Get the map renderer. - * @return {ol.renderer.Map} Renderer + * @return {module:ol/renderer/Map~Map} Renderer */ PluggableMap.prototype.getRenderer = function() { return this.renderer_; @@ -804,24 +799,24 @@ PluggableMap.prototype.getRenderer = function() { /** * Get the size of this map. - * @return {ol.Size|undefined} The size in pixels of the map in the DOM. + * @return {module:ol/types~Size|undefined} The size in pixels of the map in the DOM. * @observable * @api */ PluggableMap.prototype.getSize = function() { - return /** @type {ol.Size|undefined} */ (this.get(MapProperty.SIZE)); + return /** @type {module:ol/types~Size|undefined} */ (this.get(MapProperty.SIZE)); }; /** * Get the view associated with this map. A view manages properties such as * center and resolution. - * @return {ol.View} The view that controls this map. + * @return {module:ol/View~View} The view that controls this map. * @observable * @api */ PluggableMap.prototype.getView = function() { - return /** @type {ol.View} */ (this.get(MapProperty.VIEW)); + return /** @type {module:ol/View~View} */ (this.get(MapProperty.VIEW)); }; @@ -838,7 +833,7 @@ PluggableMap.prototype.getViewport = function() { /** * Get the element that serves as the container for overlays. Elements added to * this container will let mousedown and touchstart events through to the map, - * so clicks and gestures on an overlay will trigger {@link ol.MapBrowserEvent} + * so clicks and gestures on an overlay will trigger {@link module:ol/MapBrowserEvent~MapBrowserEvent} * events. * @return {!Element} The map's overlay container. */ @@ -851,7 +846,7 @@ PluggableMap.prototype.getOverlayContainer = function() { * Get the element that serves as a container for overlays that don't allow * event propagation. Elements added to this container won't let mousedown and * touchstart events through to the map, so clicks and gestures on an overlay - * don't trigger any {@link ol.MapBrowserEvent}. + * don't trigger any {@link module:ol/MapBrowserEvent~MapBrowserEvent}. * @return {!Element} The map's overlay container that stops events. */ PluggableMap.prototype.getOverlayContainerStopEvent = function() { @@ -860,9 +855,9 @@ PluggableMap.prototype.getOverlayContainerStopEvent = function() { /** - * @param {ol.Tile} tile Tile. + * @param {module:ol/Tile~Tile} tile Tile. * @param {string} tileSourceKey Tile source key. - * @param {ol.Coordinate} tileCenter Tile center. + * @param {module:ol/types~Coordinate} tileCenter Tile center. * @param {number} tileResolution Tile resolution. * @return {number} Tile priority. */ @@ -901,7 +896,7 @@ PluggableMap.prototype.handleBrowserEvent = function(browserEvent, opt_type) { /** - * @param {ol.MapBrowserEvent} mapBrowserEvent The event to handle. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent The event to handle. */ PluggableMap.prototype.handleMapBrowserEvent = function(mapBrowserEvent) { if (!this.frameState_) { @@ -1128,8 +1123,8 @@ PluggableMap.prototype.render = function() { /** * Remove the given control from the map. - * @param {ol.control.Control} control Control. - * @return {ol.control.Control|undefined} The removed control (or undefined + * @param {module:ol/control/Control~Control} control Control. + * @return {module:ol/control/Control~Control|undefined} The removed control (or undefined * if the control was not found). * @api */ @@ -1140,8 +1135,8 @@ PluggableMap.prototype.removeControl = function(control) { /** * Remove the given interaction from the map. - * @param {ol.interaction.Interaction} interaction Interaction to remove. - * @return {ol.interaction.Interaction|undefined} The removed interaction (or + * @param {module:ol/interaction/Interaction~Interaction} interaction Interaction to remove. + * @return {module:ol/interaction/Interaction~Interaction|undefined} The removed interaction (or * undefined if the interaction was not found). * @api */ @@ -1152,8 +1147,8 @@ PluggableMap.prototype.removeInteraction = function(interaction) { /** * Removes the given layer from the map. - * @param {ol.layer.Base} layer Layer. - * @return {ol.layer.Base|undefined} The removed layer (or undefined if the + * @param {module:ol/layer/Base~Base} layer Layer. + * @return {module:ol/layer/Base~Base|undefined} The removed layer (or undefined if the * layer was not found). * @api */ @@ -1165,8 +1160,8 @@ PluggableMap.prototype.removeLayer = function(layer) { /** * Remove the given overlay from the map. - * @param {ol.Overlay} overlay Overlay. - * @return {ol.Overlay|undefined} The removed overlay (or undefined + * @param {module:ol/Overlay~Overlay} overlay Overlay. + * @return {module:ol/Overlay~Overlay|undefined} The removed overlay (or undefined * if the overlay was not found). * @api */ @@ -1271,7 +1266,7 @@ PluggableMap.prototype.renderFrame_ = function(time) { /** * Sets the layergroup of this map. - * @param {ol.layer.Group} layerGroup A layer group containing the layers in + * @param {module:ol/layer/Group~Group} layerGroup A layer group containing the layers in * this map. * @observable * @api @@ -1283,7 +1278,7 @@ PluggableMap.prototype.setLayerGroup = function(layerGroup) { /** * Set the size of this map. - * @param {ol.Size|undefined} size The size in pixels of the map in the DOM. + * @param {module:ol/types~Size|undefined} size The size in pixels of the map in the DOM. * @observable * @api */ @@ -1306,7 +1301,7 @@ PluggableMap.prototype.setTarget = function(target) { /** * Set the view for this map. - * @param {ol.View} view The view that controls this map. + * @param {module:ol/View~View} view The view that controls this map. * @observable * @api */ @@ -1316,7 +1311,7 @@ PluggableMap.prototype.setView = function(view) { /** - * @param {ol.Feature} feature Feature. + * @param {module:ol/Feature~Feature} feature Feature. */ PluggableMap.prototype.skipFeature = function(feature) { const featureUid = getUid(feature).toString(); @@ -1354,7 +1349,7 @@ PluggableMap.prototype.updateSize = function() { /** - * @param {ol.Feature} feature Feature. + * @param {module:ol/Feature~Feature} feature Feature. */ PluggableMap.prototype.unskipFeature = function(feature) { const featureUid = getUid(feature).toString(); @@ -1364,7 +1359,7 @@ PluggableMap.prototype.unskipFeature = function(feature) { /** - * @type {Array.} + * @type {Array.} * @const */ const DEFAULT_RENDERER_TYPES = [ @@ -1375,7 +1370,7 @@ const DEFAULT_RENDERER_TYPES = [ /** * @param {MapOptions} options Map options. - * @return {ol.MapOptionsInternal} Internal map options. + * @return {module:ol/PluggableMap~MapOptionsInternal} Internal map options. */ function createOptionsInternal(options) { @@ -1404,7 +1399,7 @@ function createOptionsInternal(options) { options.view : new View(); /** - * @type {Array.} + * @type {Array.} */ let rendererTypes; @@ -1416,7 +1411,7 @@ function createOptionsInternal(options) { } else { assert(false, 46); // Incorrect format for `renderer` option } - if (rendererTypes.indexOf(/** @type {ol.renderer.Type} */ ('dom')) >= 0) { + if (rendererTypes.indexOf(/** @type {module:ol/renderer/Type} */ ('dom')) >= 0) { rendererTypes = rendererTypes.concat(DEFAULT_RENDERER_TYPES); } } else { @@ -1450,7 +1445,7 @@ function createOptionsInternal(options) { controls = new Collection(options.controls.slice()); } else { assert(options.controls instanceof Collection, - 47); // Expected `controls` to be an array or an `ol.Collection` + 47); // Expected `controls` to be an array or an `module:ol/Collection~Collection` controls = options.controls; } } @@ -1461,7 +1456,7 @@ function createOptionsInternal(options) { interactions = new Collection(options.interactions.slice()); } else { assert(options.interactions instanceof Collection, - 48); // Expected `interactions` to be an array or an `ol.Collection` + 48); // Expected `interactions` to be an array or an `module:ol/Collection~Collection` interactions = options.interactions; } } @@ -1472,7 +1467,7 @@ function createOptionsInternal(options) { overlays = new Collection(options.overlays.slice()); } else { assert(options.overlays instanceof Collection, - 49); // Expected `overlays` to be an array or an `ol.Collection` + 49); // Expected `overlays` to be an array or an `module:ol/Collection~Collection` overlays = options.overlays; } } else { diff --git a/src/ol/interaction/Interaction.js b/src/ol/interaction/Interaction.js index 5cf730339b..4616ce95aa 100644 --- a/src/ol/interaction/Interaction.js +++ b/src/ol/interaction/Interaction.js @@ -10,9 +10,13 @@ import {clamp} from '../math.js'; /** * Object literal with config options for interactions. - * @typedef {{handleEvent: function(ol.MapBrowserEvent):boolean}} + * @typedef {Object} InteractionOptions + * @property {function(module:ol/MapBrowserEvent~MapBrowserEvent):boolean} handleEvent + * Method called by the map to notify the interaction that a browser event was + * dispatched to the map. If the function returns a falsy value, propagation of + * the event to other interactions in the map's interactions chain will be + * prevented (this includes functions with no explicit return). */ -export let InteractionOptions; /** @@ -21,21 +25,15 @@ export let InteractionOptions; * instantiated in apps. * User actions that change the state of the map. Some are similar to controls, * but are not associated with a DOM element. - * For example, {@link ol.interaction.KeyboardZoom} is functionally the same as - * {@link ol.control.Zoom}, but triggered by a keyboard event not a button - * element event. + * For example, {@link module:ol/interaction/KeyboardZoom~KeyboardZoom} is + * functionally the same as {@link module:ol/control/Zoom~Zoom}, but triggered + * by a keyboard event not a button element event. * Although interactions do not have a DOM element, some of them do render * vectors and so are visible on the screen. * * @constructor - * @param {InteractionOptions} options Options. - * @param {function(ol.MapBrowserEvent):boolean} options.handleEvent Method - * called by the map to notify the interaction that a browser event was - * dispatched to the map. If the function returns a falsy value, - * propagation of the event to other interactions in the map's interactions - * chain will be prevented (this includes functions with no explicit - * return). - * @extends {ol.Object} + * @param {module:ol/interaction/Interaction~InteractionOptions} options Options. + * @extends {module:ol/Object~Object} * @api */ const Interaction = function(options) { @@ -44,14 +42,14 @@ const Interaction = function(options) { /** * @private - * @type {ol.PluggableMap} + * @type {module:ol/PluggableMap~PluggableMap} */ this.map_ = null; this.setActive(true); /** - * @type {function(ol.MapBrowserEvent):boolean} + * @type {function(module:ol/MapBrowserEvent~MapBrowserEvent):boolean} */ this.handleEvent = options.handleEvent; @@ -73,7 +71,7 @@ Interaction.prototype.getActive = function() { /** * Get the map associated with this interaction. - * @return {ol.PluggableMap} Map. + * @return {module:ol/PluggableMap~PluggableMap} Map. * @api */ Interaction.prototype.getMap = function() { @@ -96,7 +94,7 @@ Interaction.prototype.setActive = function(active) { * Remove the interaction from its current map and attach it to the new map. * Subclasses may set up event handlers to get notified about changes to * the map here. - * @param {ol.PluggableMap} map Map. + * @param {module:ol/PluggableMap~PluggableMap} map Map. */ Interaction.prototype.setMap = function(map) { this.map_ = map; @@ -104,8 +102,8 @@ Interaction.prototype.setMap = function(map) { /** - * @param {ol.View} view View. - * @param {ol.Coordinate} delta Delta. + * @param {module:ol/View~View} view View. + * @param {module:ol/types~Coordinate} delta Delta. * @param {number=} opt_duration Duration. */ export function pan(view, delta, opt_duration) { @@ -127,9 +125,9 @@ export function pan(view, delta, opt_duration) { /** - * @param {ol.View} view View. + * @param {module:ol/View~View} view View. * @param {number|undefined} rotation Rotation. - * @param {ol.Coordinate=} opt_anchor Anchor coordinate. + * @param {module:ol/types~Coordinate=} opt_anchor Anchor coordinate. * @param {number=} opt_duration Duration. */ export function rotate(view, rotation, opt_anchor, opt_duration) { @@ -139,9 +137,9 @@ export function rotate(view, rotation, opt_anchor, opt_duration) { /** - * @param {ol.View} view View. + * @param {module:ol/View~View} view View. * @param {number|undefined} rotation Rotation. - * @param {ol.Coordinate=} opt_anchor Anchor coordinate. + * @param {module:ol/types~Coordinate=} opt_anchor Anchor coordinate. * @param {number=} opt_duration Duration. */ export function rotateWithoutConstraints(view, rotation, opt_anchor, opt_duration) { @@ -163,9 +161,9 @@ export function rotateWithoutConstraints(view, rotation, opt_anchor, opt_duratio /** - * @param {ol.View} view View. + * @param {module:ol/View~View} view View. * @param {number|undefined} resolution Resolution to go to. - * @param {ol.Coordinate=} opt_anchor Anchor coordinate. + * @param {module:ol/types~Coordinate=} opt_anchor Anchor coordinate. * @param {number=} opt_duration Duration. * @param {number=} opt_direction Zooming direction; > 0 indicates * zooming out, in which case the constraints system will select @@ -183,9 +181,9 @@ export function zoom(view, resolution, opt_anchor, opt_duration, opt_direction) /** - * @param {ol.View} view View. + * @param {module:ol/View~View} view View. * @param {number} delta Delta from previous zoom level. - * @param {ol.Coordinate=} opt_anchor Anchor coordinate. + * @param {module:ol/types~Coordinate=} opt_anchor Anchor coordinate. * @param {number=} opt_duration Duration. */ export function zoomByDelta(view, delta, opt_anchor, opt_duration) { @@ -221,9 +219,9 @@ export function zoomByDelta(view, delta, opt_anchor, opt_duration) { /** - * @param {ol.View} view View. + * @param {module:ol/View~View} view View. * @param {number|undefined} resolution Resolution to go to. - * @param {ol.Coordinate=} opt_anchor Anchor coordinate. + * @param {module:ol/types~Coordinate=} opt_anchor Anchor coordinate. * @param {number=} opt_duration Duration. */ export function zoomWithoutConstraints(view, resolution, opt_anchor, opt_duration) { diff --git a/src/ol/sphere.js b/src/ol/sphere.js index 48af84e903..cbc9937b58 100644 --- a/src/ol/sphere.js +++ b/src/ol/sphere.js @@ -1,9 +1,9 @@ /** -* @license -* Latitude/longitude spherical geodesy formulae taken from -* http://www.movable-type.co.uk/scripts/latlong.html -* Licensed under CC-BY-3.0. -*/ + * @license + * Latitude/longitude spherical geodesy formulae taken from + * http://www.movable-type.co.uk/scripts/latlong.html + * Licensed under CC-BY-3.0. + */ /** * @module ol/sphere @@ -13,12 +13,15 @@ import GeometryType from './geom/GeometryType.js'; /** - * Object literal with options for the {@link getLength} or - * {@link getArea} functions. - * @typedef {{projection: (ol.ProjectionLike|undefined), - * radius: (number|undefined)}} + * Object literal with options for the {@link getLength} or {@link getArea} + * functions. + * @typedef {Object} SphereMetricOptions + * @property {module:ol/types~ProjectionLike} [projection='EPSG:3857'] + * Projection of the geometry. By default, the geometry is assumed to be in + * Web Mercator. + * @property {number} [radius=6371008.8] Sphere radius. By default, the radius of the + * earth is used (Clarke 1866 Authalic Sphere). */ -export let SphereMetricOptions; /** @@ -71,15 +74,10 @@ function getLengthInternal(coordinates, radius) { * great circle distances between coordinates. For polygons, the length is * the sum of all rings. For points, the length is zero. For multi-part * geometries, the length is the sum of the length of each part. - * @param {ol.geom.Geometry} geometry A geometry. - * @param {SphereMetricOptions=} opt_options Options for the length - * calculation. By default, geometries are assumed to be in 'EPSG:3857'. - * You can change this by providing a `projection` option. - * @param {(ol.ProjectionLike|undefined)} opt_options.projection Projection of - * the geometry. By default, the geometry is assumed to be in EPSG:3857 - * (Web Mercator). - * @param {(number|undefined)} opt_options.radius Sphere radius. Defaults to - * the Earth's mean radius using the WGS84 ellipsoid. + * @param {module:ol/geom/Geometry~Geometry} geometry A geometry. + * @param {module:ol/sphere~SphereMetricOptions=} opt_options Options for the + * length calculation. By default, geometries are assumed to be in 'EPSG:3857'. + * You can change this by providing a `projection` option. * @return {number} The spherical length (in meters). * @api */ @@ -100,20 +98,20 @@ export function getLength(geometry, opt_options) { } case GeometryType.LINE_STRING: case GeometryType.LINEAR_RING: { - coordinates = /** @type {ol.geom.SimpleGeometry} */ (geometry).getCoordinates(); + coordinates = /** @type {module:ol/geom/SimpleGeometry~SimpleGeometry} */ (geometry).getCoordinates(); length = getLengthInternal(coordinates, radius); break; } case GeometryType.MULTI_LINE_STRING: case GeometryType.POLYGON: { - coordinates = /** @type {ol.geom.SimpleGeometry} */ (geometry).getCoordinates(); + coordinates = /** @type {module:ol/geom/SimpleGeometry~SimpleGeometry} */ (geometry).getCoordinates(); for (i = 0, ii = coordinates.length; i < ii; ++i) { length += getLengthInternal(coordinates[i], radius); } break; } case GeometryType.MULTI_POLYGON: { - coordinates = /** @type {ol.geom.SimpleGeometry} */ (geometry).getCoordinates(); + coordinates = /** @type {module:ol/geom/SimpleGeometry~SimpleGeometry} */ (geometry).getCoordinates(); for (i = 0, ii = coordinates.length; i < ii; ++i) { coords = coordinates[i]; for (j = 0, jj = coords.length; j < jj; ++j) { @@ -123,7 +121,7 @@ export function getLength(geometry, opt_options) { break; } case GeometryType.GEOMETRY_COLLECTION: { - const geometries = /** @type {ol.geom.GeometryCollection} */ (geometry).getGeometries(); + const geometries = /** @type {module:ol/geom/GeometryCollection~GeometryCollection} */ (geometry).getGeometries(); for (i = 0, ii = geometries.length; i < ii; ++i) { length += getLength(geometries[i], opt_options); } @@ -145,7 +143,7 @@ export function getLength(geometry, opt_options) { * Polygons on a Sphere", JPL Publication 07-03, Jet Propulsion * Laboratory, Pasadena, CA, June 2007 * - * @param {Array.} coordinates List of coordinates of a linear + * @param {Array.} coordinates List of coordinates of a linear * ring. If the ring is oriented clockwise, the area will be positive, * otherwise it will be negative. * @param {number} radius The sphere radius. @@ -172,8 +170,8 @@ function getAreaInternal(coordinates, radius) { /** * Get the spherical area of a geometry. This is the area (in meters) assuming * that polygon edges are segments of great circles on a sphere. - * @param {ol.geom.Geometry} geometry A geometry. - * @param {SphereMetricOptions=} opt_options Options for the area + * @param {module:ol/geom/Geometry~Geometry} geometry A geometry. + * @param {module:ol/sphere~SphereMetricOptions=} opt_options Options for the area * calculation. By default, geometries are assumed to be in 'EPSG:3857'. * You can change this by providing a `projection` option. * @return {number} The spherical area (in square meters). @@ -198,7 +196,7 @@ export function getArea(geometry, opt_options) { break; } case GeometryType.POLYGON: { - coordinates = /** @type {ol.geom.Polygon} */ (geometry).getCoordinates(); + coordinates = /** @type {module:ol/geom/Polygon~Polygon} */ (geometry).getCoordinates(); area = Math.abs(getAreaInternal(coordinates[0], radius)); for (i = 1, ii = coordinates.length; i < ii; ++i) { area -= Math.abs(getAreaInternal(coordinates[i], radius)); @@ -206,7 +204,7 @@ export function getArea(geometry, opt_options) { break; } case GeometryType.MULTI_POLYGON: { - coordinates = /** @type {ol.geom.SimpleGeometry} */ (geometry).getCoordinates(); + coordinates = /** @type {module:ol/geom/SimpleGeometry~SimpleGeometry} */ (geometry).getCoordinates(); for (i = 0, ii = coordinates.length; i < ii; ++i) { coords = coordinates[i]; area += Math.abs(getAreaInternal(coords[0], radius)); @@ -217,7 +215,7 @@ export function getArea(geometry, opt_options) { break; } case GeometryType.GEOMETRY_COLLECTION: { - const geometries = /** @type {ol.geom.GeometryCollection} */ (geometry).getGeometries(); + const geometries = /** @type {module:ol/geom/GeometryCollection~GeometryCollection} */ (geometry).getGeometries(); for (i = 0, ii = geometries.length; i < ii; ++i) { area += getArea(geometries[i], opt_options); } @@ -234,13 +232,13 @@ export function getArea(geometry, opt_options) { /** * Returns the coordinate at the given distance and bearing from `c1`. * - * @param {ol.Coordinate} c1 The origin point (`[lon, lat]` in degrees). + * @param {module:ol/types~Coordinate} c1 The origin point (`[lon, lat]` in degrees). * @param {number} distance The great-circle distance between the origin * point and the target point. * @param {number} bearing The bearing (in radians). * @param {number=} opt_radius The sphere radius to use. Defaults to the Earth's * mean radius using the WGS84 ellipsoid. - * @return {ol.Coordinate} The target point. + * @return {module:ol/types~Coordinate} The target point. */ export function offset(c1, distance, bearing, opt_radius) { const radius = opt_radius || DEFAULT_RADIUS; diff --git a/src/ol/typedefs.js b/src/ol/typedefs.js index 53d99bf7b8..88c9a8c950 100644 --- a/src/ol/typedefs.js +++ b/src/ol/typedefs.js @@ -177,13 +177,6 @@ ol.ColorLike; ol.Constraints; -/** - * An array of numbers representing an xy coordinate. Example: `[16, 48]`. - * @typedef {Array.} - */ -ol.Coordinate; - - /** * A function that takes a {@link ol.Coordinate} and transforms it into a * `{string}`. @@ -236,20 +229,6 @@ ol.DrawGeometryFunctionType; ol.EventsConditionType; -/** - * Key to use with {@link ol.Observable#unByKey}. - * - * @typedef {{bindTo: (Object|undefined), - * boundListener: (ol.EventsListenerFunctionType|undefined), - * callOnce: boolean, - * deleteIndex: (number|undefined), - * listener: ol.EventsListenerFunctionType, - * target: (EventTarget|ol.events.EventTarget), - * type: string}} - */ -ol.EventsKey; - - /** * Listener function. This function is called with an event object as argument. * When the function returns `false`, event propagation will stop. @@ -265,13 +244,6 @@ ol.EventsListenerFunctionType; ol.EventTargetLike; -/** - * An array of numbers representing an extent: `[minx, miny, maxx, maxy]`. - * @typedef {Array.} - */ -ol.Extent; - - /** * {@link ol.source.Vector} sources use a function of this type to load * features. @@ -302,15 +274,6 @@ ol.FeatureLoader; ol.FeatureUrlFunction; -/** - * @typedef {{ - * geom: ol.geom.Point, - * text: string - * }} - */ -ol.GraticuleLabelDataType; - - /** * A function that is called to trigger asynchronous canvas drawing. It is * called with a "done" callback that should be called when drawing is done. @@ -403,25 +366,6 @@ ol.LoadingStrategy; ol.LRUCacheEntry; -/** - * @typedef {{controls: (ol.Collection.|undefined), - * interactions: (ol.Collection.|undefined), - * keyboardEventTarget: (Element|Document), - * overlays: ol.Collection., - * mapRendererPlugin: olx.MapRendererPlugin, - * values: Object.}} - */ -ol.MapOptionsInternal; - - -/** - * An array representing an affine 2d transformation for use with - * {@link ol.transform} functions. The array has 6 elements. - * @typedef {!Array.} - */ -ol.Transform; - - /** * @typedef {{depth: (Array.|undefined), * feature: ol.Feature, @@ -433,20 +377,6 @@ ol.Transform; ol.ModifySegmentDataType; -/** - * An array with two elements, representing a pixel. The first element is the - * x-coordinate, the second the y-coordinate of the pixel. - * @typedef {Array.} - */ -ol.Pixel; - - -/** - * @typedef {function(ol.PluggableMap, ?olx.FrameState): boolean} - */ -ol.PostRenderFunction; - - /** * Function to perform manipulations before rendering. This function is called * with the {@link ol.Map} as first and an optional {@link olx.FrameState} as @@ -457,14 +387,6 @@ ol.PostRenderFunction; ol.PreRenderFunction; -/** - * A projection as {@link ol.proj.Projection}, SRS identifier string or - * undefined. - * @typedef {ol.proj.Projection|string|undefined} - */ -ol.ProjectionLike; - - /** * A function that takes an array of input data, performs some operation, and * returns an array of ouput data. @@ -553,13 +475,6 @@ ol.RotationConstraintType; ol.SelectFilterFunction; -/** - * An array of numbers representing a size: `[width, height]`. - * @typedef {Array.} - */ -ol.Size; - - /** * @typedef {{ * snapped: {boolean}, @@ -731,17 +646,6 @@ ol.TileReplayState; ol.TileUrlFunctionType; -/** - * A transform function accepts an array of input coordinate values, an optional - * output array, and an optional dimension (default should be 2). The function - * transforms the input coordinate values, populates the output array, and - * returns the output array. - * - * @typedef {function(Array., Array.=, number=): Array.} - */ -ol.TransformFunction; - - /** * An animation configuration * diff --git a/src/ol/types.js b/src/ol/types.js new file mode 100644 index 0000000000..50eda27d03 --- /dev/null +++ b/src/ol/types.js @@ -0,0 +1,68 @@ +/** + * @module ol/types + */ + + +/** + * An array of numbers representing an xy coordinate. Example: `[16, 48]`. + * @typedef {Array.} Coordinate + * @api + */ + +/** + * Key to use with {@link module:ol/Observable~Observable#unByKey}. + * @typedef {Object} EventsKey + * @property {Object} [bindTo] + * @property {ol.EventsListenerFunctionType} [boundListener] + * @property {boolean} callOnce + * @property {number} [deleteIndex] + * @property {ol.EventsListenerFunctionType} listener + * @property {EventTarget|ol.events.EventTarget} target + * @property {string} type + */ + +/** + * An array of numbers representing an extent: `[minx, miny, maxx, maxy]`. + * @typedef {Array.} Extent + * @api + */ + +/** + * An array with two elements, representing a pixel. The first element is the + * x-coordinate, the second the y-coordinate of the pixel. + * @typedef {Array.} Pixel + * @api + */ + +/** + * @typedef {function(module:ol/PluggableMap~PluggableMap, ?olx.FrameState): boolean} PostRenderFunction + */ + +/** + * A projection as {@link module:ol/proj/Projection~Projection}, SRS identifier + * string or undefined. + * @typedef {module:ol/proj/Projection~Projection|string|undefined} ProjectionLike + * @api + */ + +/** + * An array of numbers representing a size: `[width, height]`. + * @typedef {Array.} Size + * @api + */ + +/** + * An array representing an affine 2d transformation for use with + * {@link module:ol/transform} functions. The array has 6 elements. + * @typedef {!Array.} Transform + */ + +/** + * A transform function accepts an array of input coordinate values, an optional + * output array, and an optional dimension (default should be 2). The function + * transforms the input coordinate values, populates the output array, and + * returns the output array. + * + * @typedef {function(Array., Array.=, number=): Array.} TransformFunction + * @api + */