diff --git a/externs/olx.js b/externs/olx.js index cd39808c64..71328756d5 100644 --- a/externs/olx.js +++ b/externs/olx.js @@ -5,23 +5,6 @@ var olx; -/** - * Options for tile constructors. - * @typedef {{transition: (number|undefined)}} - */ -olx.TileOptions; - - -/** - * A duration for tile opacity transitions. By default, tiles will render with - * an opacity transition that lasts 250 ms. To change the duration, pass a - * number in milliseconds. A duration of 0 disables the opacity transition. - * @type {number|undefined} - * @api - */ -olx.TileOptions.prototype.transition; - - /** * Object literal with options for the {@link ol.Map#forEachFeatureAtPixel} and * {@link ol.Map#hasFeatureAtPixel} methods. @@ -52,153 +35,6 @@ olx.AtPixelOptions.prototype.layerFilter; olx.AtPixelOptions.prototype.hitTolerance; -/** - * Object literal with config options for the overlay. - * @typedef {{id: (number|string|undefined), - * element: (Element|undefined), - * offset: (Array.|undefined), - * position: (ol.Coordinate|undefined), - * positioning: (ol.OverlayPositioning|string|undefined), - * stopEvent: (boolean|undefined), - * insertFirst: (boolean|undefined), - * autoPan: (boolean|undefined), - * autoPanAnimation: (olx.OverlayPanOptions|undefined), - * autoPanMargin: (number|undefined), - * className: (string|undefined)}} - */ -olx.OverlayOptions; - - -/** - * Set the overlay id. The overlay id can be used with the - * {@link ol.Map#getOverlayById} method. - * @type {number|string|undefined} - * @api - */ -olx.OverlayOptions.prototype.id; - - -/** - * The overlay element. - * @type {Element|undefined} - * @api - */ -olx.OverlayOptions.prototype.element; - - -/** - * Offsets in pixels used when positioning the overlay. The first element in the - * array is the horizontal offset. A positive value shifts the overlay right. - * The second element in the array is the vertical offset. A positive value - * shifts the overlay down. Default is `[0, 0]`. - * @type {Array.|undefined} - * @api - */ -olx.OverlayOptions.prototype.offset; - - -/** - * The overlay position in map projection. - * @type {ol.Coordinate|undefined} - * @api - */ -olx.OverlayOptions.prototype.position; - - -/** - * Defines how the overlay is actually positioned with respect to its `position` - * property. Possible values are `'bottom-left'`, `'bottom-center'`, - * `'bottom-right'`, `'center-left'`, `'center-center'`, `'center-right'`, - * `'top-left'`, `'top-center'`, and `'top-right'`. Default is `'top-left'`. - * @type {ol.OverlayPositioning|string|undefined} - * @api - */ -olx.OverlayOptions.prototype.positioning; - - -/** - * Whether event propagation to the map viewport should be stopped. Default is - * `true`. If `true` the overlay is placed in the same container as that of the - * controls (CSS class name `ol-overlaycontainer-stopevent`); if `false` it is - * placed in the container with CSS class name `ol-overlaycontainer`. - * @type {boolean|undefined} - * @api - */ -olx.OverlayOptions.prototype.stopEvent; - - -/** - * Whether the overlay is inserted first in the overlay container, or appended. - * Default is `true`. If the overlay is placed in the same container as that of - * the controls (see the `stopEvent` option) you will probably set `insertFirst` - * to `true` so the overlay is displayed below the controls. - * @type {boolean|undefined} - * @api - */ -olx.OverlayOptions.prototype.insertFirst; - - -/** - * If set to `true` the map is panned when calling `setPosition`, so that the - * overlay is entirely visible in the current viewport. - * The default is `false`. - * @type {boolean|undefined} - * @api - */ -olx.OverlayOptions.prototype.autoPan; - - -/** - * The animation options used to pan the overlay into view. This animation - * is only used when `autoPan` is enabled. A `duration` and `easing` may be - * provided to customize the animation. - * @type {olx.OverlayPanOptions|undefined} - * @api - */ -olx.OverlayOptions.prototype.autoPanAnimation; - - -/** - * The margin (in pixels) between the overlay and the borders of the map when - * autopanning. The default is `20`. - * @type {number|undefined} - * @api - */ -olx.OverlayOptions.prototype.autoPanMargin; - -/** - * CSS class name. Default is `ol-overlay-container ol-selectable`. - * @type {string|undefined} - * @api - */ -olx.OverlayOptions.prototype.className; - -/** - * @typedef {{ - * duration: (number|undefined), - * easing: (undefined|function(number):number) - * }} - */ -olx.OverlayPanOptions; - - -/** - * The duration of the animation in milliseconds. Default is `1000`. - * @type {number|undefined} - * @api - */ -olx.OverlayPanOptions.prototype.duration; - - -/** - * The easing function to use. Can be an {@link ol.easing} or a custom function. - * Default is {@link ol.easing.inAndOut}. - * @type {undefined|function(number):number} - * @api - */ -olx.OverlayPanOptions.prototype.easing; - - /** * Object literal with config options for the projection. * @typedef {{code: string, @@ -281,170 +117,6 @@ olx.ProjectionOptions.prototype.worldExtent; olx.ProjectionOptions.prototype.getPointResolution; -/** - * Object literal with config options for the view. - * @typedef {{center: (ol.Coordinate|undefined), - * constrainRotation: (boolean|number|undefined), - * enableRotation: (boolean|undefined), - * extent: (ol.Extent|undefined), - * minResolution: (number|undefined), - * maxResolution: (number|undefined), - * minZoom: (number|undefined), - * maxZoom: (number|undefined), - * projection: ol.ProjectionLike, - * resolution: (number|undefined), - * resolutions: (Array.|undefined), - * rotation: (number|undefined), - * zoom: (number|undefined), - * zoomFactor: (number|undefined)}} - */ -olx.ViewOptions; - - -/** - * The initial center for the view. The coordinate system for the center is - * specified with the `projection` option. Default is `undefined`, and layer - * sources will not be fetched if this is not set. - * @type {ol.Coordinate|undefined} - * @api - */ -olx.ViewOptions.prototype.center; - - -/** - * Rotation constraint. `false` means no constraint. `true` means no constraint, - * but snap to zero near zero. A number constrains the rotation to that number - * of values. For example, `4` will constrain the rotation to 0, 90, 180, and - * 270 degrees. The default is `true`. - * @type {boolean|number|undefined} - * @api - */ -olx.ViewOptions.prototype.constrainRotation; - - -/** - * Enable rotation. Default is `true`. If `false` a rotation constraint that - * always sets the rotation to zero is used. The `constrainRotation` option - * has no effect if `enableRotation` is `false`. - * @type {boolean|undefined} - * @api - */ -olx.ViewOptions.prototype.enableRotation; - - -/** - * The extent that constrains the center, in other words, center cannot be set - * outside this extent. Default is `undefined`. - * @type {ol.Extent|undefined} - * @api - */ -olx.ViewOptions.prototype.extent; - - -/** - * The maximum resolution used to determine the resolution constraint. It is - * used together with `minResolution` (or `maxZoom`) and `zoomFactor`. If - * unspecified it is calculated in such a way that the projection's validity - * extent fits in a 256x256 px tile. If the projection is Spherical Mercator - * (the default) then `maxResolution` defaults to `40075016.68557849 / 256 = - * 156543.03392804097`. - * @type {number|undefined} - * @api - */ -olx.ViewOptions.prototype.maxResolution; - - -/** - * The minimum resolution used to determine the resolution constraint. It is - * used together with `maxResolution` (or `minZoom`) and `zoomFactor`. If - * unspecified it is calculated assuming 29 zoom levels (with a factor of 2). - * If the projection is Spherical Mercator (the default) then `minResolution` - * defaults to `40075016.68557849 / 256 / Math.pow(2, 28) = - * 0.0005831682455839253`. - * @type {number|undefined} - * @api - */ -olx.ViewOptions.prototype.minResolution; - - -/** - * The maximum zoom level used to determine the resolution constraint. It is - * used together with `minZoom` (or `maxResolution`) and `zoomFactor`. Default - * is `28`. Note that if `minResolution` is also provided, it is given - * precedence over `maxZoom`. - * @type {number|undefined} - * @api - */ -olx.ViewOptions.prototype.maxZoom; - - -/** - * The minimum zoom level used to determine the resolution constraint. It is - * used together with `maxZoom` (or `minResolution`) and `zoomFactor`. Default - * is `0`. Note that if `maxResolution` is also provided, it is given - * precedence over `minZoom`. - * @type {number|undefined} - * @api - */ -olx.ViewOptions.prototype.minZoom; - - -/** - * The projection. Default is `EPSG:3857` (Spherical Mercator). - * @type {ol.ProjectionLike} - * @api - */ -olx.ViewOptions.prototype.projection; - - -/** - * The initial resolution for the view. The units are `projection` units per - * pixel (e.g. meters per pixel). An alternative to setting this is to set - * `zoom`. Default is `undefined`, and layer sources will not be fetched if - * neither this nor `zoom` are defined. - * @type {number|undefined} - * @api - */ -olx.ViewOptions.prototype.resolution; - - -/** - * Resolutions to determine the resolution constraint. If set the - * `maxResolution`, `minResolution`, `minZoom`, `maxZoom`, and `zoomFactor` - * options are ignored. - * @type {Array.|undefined} - * @api - */ -olx.ViewOptions.prototype.resolutions; - - -/** - * The initial rotation for the view in radians (positive rotation clockwise). - * Default is `0`. - * @type {number|undefined} - * @api - */ -olx.ViewOptions.prototype.rotation; - - -/** - * Only used if `resolution` is not defined. Zoom level used to calculate the - * initial resolution for the view. The initial resolution is determined using - * the `ol.View#constrainResolution` method. - * @type {number|undefined} - * @api - */ -olx.ViewOptions.prototype.zoom; - - -/** - * The zoom factor used to determine the resolution constraint. Default is `2`. - * @type {number|undefined} - * @api - */ -olx.ViewOptions.prototype.zoomFactor; - - /** * @typedef {{ * center: (ol.Coordinate|undefined), @@ -646,65 +318,6 @@ olx.control.ControlOptions.prototype.render; olx.control.ControlOptions.prototype.target; -/** - * @typedef {{attribution: (boolean|undefined), - * attributionOptions: (olx.control.AttributionOptions|undefined), - * rotate: (boolean|undefined), - * rotateOptions: (olx.control.RotateOptions|undefined), - * zoom: (boolean|undefined), - * zoomOptions: (olx.control.ZoomOptions|undefined)}} - */ -olx.control.DefaultsOptions; - - -/** - * Attribution. Default is `true`. - * @type {boolean|undefined} - * @api - */ -olx.control.DefaultsOptions.prototype.attribution; - - -/** - * Attribution options. - * @type {olx.control.AttributionOptions|undefined} - * @api - */ -olx.control.DefaultsOptions.prototype.attributionOptions; - - -/** - * Rotate. Default is `true`. - * @type {boolean|undefined} - * @api - */ -olx.control.DefaultsOptions.prototype.rotate; - - -/** - * Rotate options. - * @type {olx.control.RotateOptions|undefined} - * @api - */ -olx.control.DefaultsOptions.prototype.rotateOptions; - - -/** - * Zoom. Default is `true`. - * @type {boolean|undefined} - * @api - */ -olx.control.DefaultsOptions.prototype.zoom; - - -/** - * Zoom options. - * @type {olx.control.ZoomOptions|undefined} - * @api - */ -olx.control.DefaultsOptions.prototype.zoomOptions; - - /** * @typedef {{className: (string|undefined), * label: (string|Node|undefined), @@ -777,7 +390,7 @@ olx.control.FullScreenOptions.prototype.source; /** * @typedef {{className: (string|undefined), - * coordinateFormat: (ol.CoordinateFormatType|undefined), + * coordinateFormat: (module:ol/coordinate~CoordinateFormat|undefined), * projection: ol.ProjectionLike, * render: (function(ol.MapEvent)|undefined), * target: (Element|string|undefined), @@ -796,7 +409,7 @@ olx.control.MousePositionOptions.prototype.className; /** * Coordinate format. - * @type {ol.CoordinateFormatType|undefined} + * @type {module:ol/coordinate~CoordinateFormat|undefined} * @api */ olx.control.MousePositionOptions.prototype.coordinateFormat; @@ -2012,114 +1625,6 @@ olx.format.WMSGetFeatureInfoOptions.prototype.layers; olx.interaction; -/** - * Interactions for the map. Default is `true` for all options. - * @typedef {{ - * altShiftDragRotate: (boolean|undefined), - * constrainResolution: (boolean|undefined), - * doubleClickZoom: (boolean|undefined), - * keyboard: (boolean|undefined), - * mouseWheelZoom: (boolean|undefined), - * shiftDragZoom: (boolean|undefined), - * dragPan: (boolean|undefined), - * pinchRotate: (boolean|undefined), - * pinchZoom: (boolean|undefined), - * zoomDelta: (number|undefined), - * zoomDuration: (number|undefined) - * }} - */ -olx.interaction.DefaultsOptions; - - -/** - * Whether Alt-Shift-drag rotate is desired. Default is `true`. - * @type {boolean|undefined} - * @api - */ -olx.interaction.DefaultsOptions.prototype.altShiftDragRotate; - - -/** - * Zoom to the closest integer zoom level after the wheel/trackpad or - * pinch gesture ends. Default is `false`. - * @type {boolean|undefined} - * @api - */ -olx.interaction.DefaultsOptions.prototype.constrainResolution; - - -/** - * Whether double click zoom is desired. Default is `true`. - * @type {boolean|undefined} - * @api - */ -olx.interaction.DefaultsOptions.prototype.doubleClickZoom; - - -/** - * Whether keyboard interaction is desired. Default is `true`. - * @type {boolean|undefined} - * @api - */ -olx.interaction.DefaultsOptions.prototype.keyboard; - - -/** - * Whether mousewheel zoom is desired. Default is `true`. - * @type {boolean|undefined} - * @api - */ -olx.interaction.DefaultsOptions.prototype.mouseWheelZoom; - - -/** - * Whether Shift-drag zoom is desired. Default is `true`. - * @type {boolean|undefined} - * @api - */ -olx.interaction.DefaultsOptions.prototype.shiftDragZoom; - - -/** - * Whether drag pan is desired. Default is `true`. - * @type {boolean|undefined} - * @api - */ -olx.interaction.DefaultsOptions.prototype.dragPan; - - -/** - * Whether pinch rotate is desired. Default is `true`. - * @type {boolean|undefined} - * @api - */ -olx.interaction.DefaultsOptions.prototype.pinchRotate; - - -/** - * Whether pinch zoom is desired. Default is `true`. - * @type {boolean|undefined} - * @api - */ -olx.interaction.DefaultsOptions.prototype.pinchZoom; - - -/** - * Zoom delta. - * @type {number|undefined} - * @api - */ -olx.interaction.DefaultsOptions.prototype.zoomDelta; - - -/** - * Zoom duration. - * @type {number|undefined} - * @api - */ -olx.interaction.DefaultsOptions.prototype.zoomDuration; - - /** * @typedef {{duration: (number|undefined), * delta: (number|undefined)}} @@ -4038,32 +3543,6 @@ olx.render.State.prototype.resolution; olx.render.State.prototype.rotation; -/** - * @typedef {{size: (ol.Size|undefined), - * pixelRatio: (number|undefined)}} - */ -olx.render.ToContextOptions; - - -/** - * Desired size of the canvas in css pixels. When provided, both canvas and css - * size will be set according to the `pixelRatio`. If not provided, the current - * canvas and css sizes will not be altered. - * @type {ol.Size|undefined} - * @api - */ -olx.render.ToContextOptions.prototype.size; - - -/** - * Pixel ratio (canvas pixel to css pixel ratio) for the canvas. Default - * is the detected device pixel ratio. - * @type {number|undefined} - * @api - */ -olx.render.ToContextOptions.prototype.pixelRatio; - - /** * Namespace. * @type {Object} @@ -7566,151 +7045,9 @@ olx.tilegrid.XYZOptions.prototype.tileSize; olx.view; -/** - * @typedef {{ - * size: (ol.Size|undefined), - * padding: (!Array.|undefined), - * constrainResolution: (boolean|undefined), - * nearest: (boolean|undefined), - * maxZoom: (number|undefined), - * minResolution: (number|undefined), - * duration: (number|undefined), - * easing: (undefined|function(number):number), - * callback: (undefined|function(boolean)) - * }} - */ -olx.view.FitOptions; - - -/** - * The size in pixels of the box to fit the extent into. Default is - * the current size of the first map in the DOM that uses this view, or - * `[100, 100]` if no such map is found. - * @type {ol.Size|undefined} - * @api - */ -olx.view.FitOptions.prototype.size; - - -/** - * Padding (in pixels) to be cleared inside the view. Values in the array are - * top, right, bottom and left padding. Default is `[0, 0, 0, 0]`. - * @type {!Array.|undefined} - * @api - */ -olx.view.FitOptions.prototype.padding; - - -/** - * Constrain the resolution. Default is `true`. - * @type {boolean|undefined} - * @api - */ -olx.view.FitOptions.prototype.constrainResolution; - - -/** - * Get the nearest extent. Default is `false`. - * @type {boolean|undefined} - * @api - */ -olx.view.FitOptions.prototype.nearest; - - -/** - * Minimum resolution that we zoom to. Default is `0`. - * @type {number|undefined} - * @api - */ -olx.view.FitOptions.prototype.minResolution; - - -/** - * Maximum zoom level that we zoom to. If `minResolution` is given, - * this property is ignored. - * @type {number|undefined} - * @api - */ -olx.view.FitOptions.prototype.maxZoom; - - -/** - * The duration of the animation in milliseconds. By default, there is no - * animations. - * @type {number|undefined} - * @api - */ -olx.view.FitOptions.prototype.duration; - - -/** - * The easing function used during the animation (defaults to {@link ol.easing.inAndOut}). - * The function will be called for each frame with a number representing a - * fraction of the animation's duration. The function should return a number - * between 0 and 1 representing the progress toward the destination state. - * @type {undefined|function(number):number} - * @api - */ -olx.view.FitOptions.prototype.easing; - - -/** - * Optional function called when the view is in it's final position. The callback will be - * called with `true` if the animation series completed on its own or `false` - * if it was cancelled. - * @type {undefined|function(boolean)} - * @api - */ -olx.view.FitOptions.prototype.callback; - - /* typedefs for object literals exposed by the library */ -/** - * @typedef {{animate: boolean, - * coordinateToPixelTransform: ol.Transform, - * extent: (null|ol.Extent), - * focus: ol.Coordinate, - * index: number, - * layerStates: Object., - * layerStatesArray: Array., - * pixelRatio: number, - * pixelToCoordinateTransform: ol.Transform, - * postRenderFunctions: Array., - * size: ol.Size, - * skippedFeatureUids: !Object., - * tileQueue: ol.TileQueue, - * time: number, - * usedTiles: Object.>, - * viewState: olx.ViewState, - * viewHints: Array., - * wantedTiles: !Object.>}} - */ -olx.FrameState; - - -/** - * @type {number} - * @api - */ -olx.FrameState.prototype.pixelRatio; - - -/** - * @type {number} - * @api - */ -olx.FrameState.prototype.time; - - -/** - * @type {olx.ViewState} - * @api - */ -olx.FrameState.prototype.viewState; - - /** * @typedef {{center: ol.Coordinate, * projection: ol.proj.Projection, @@ -7788,49 +7125,3 @@ olx.style.AtlasManagerOptions.prototype.maxSize; * @api */ olx.style.AtlasManagerOptions.prototype.space; - - -/** - * @typedef {{handles: function(ol.renderer.Type):boolean, - * create: function(Element, ol.PluggableMap):ol.renderer.Map}} - */ -olx.MapRendererPlugin; - - -/** - * Determine if this renderer handles the provided layer. - * @type {function(ol.renderer.Type):boolean} - * @api - */ -olx.MapRendererPlugin.prototype.handles; - - -/** - * Create the map renderer. - * @type {function(Element, ol.PluggableMap):ol.renderer.Map} - * @api - */ -olx.MapRendererPlugin.prototype.create; - - -/** - * @typedef {{handles: function(ol.renderer.Type, ol.layer.Layer):boolean, - * create: function(ol.renderer.Map, ol.layer.Layer):ol.renderer.Layer}} - */ -olx.LayerRendererPlugin; - - -/** - * Determine if this renderer handles the provided layer. - * @type {function(ol.renderer.Type, ol.layer.Layer):boolean} - * @api - */ -olx.LayerRendererPlugin.prototype.handles; - - -/** - * Create a layer renderer. - * @type {function(ol.renderer.Map, ol.layer.Layer):ol.renderer.Layer} - * @api - */ -olx.LayerRendererPlugin.prototype.create; diff --git a/src/ol/CanvasMap.js b/src/ol/CanvasMap.js index 16f0ffa828..a896319eac 100644 --- a/src/ol/CanvasMap.js +++ b/src/ol/CanvasMap.js @@ -29,47 +29,53 @@ registerMultiple(PluginType.LAYER_RENDERER, [ * The map is the core component of OpenLayers. For a map to render, a view, * one or more layers, and a target container are needed: * - * var map = new ol.CanvasMap({ - * view: new ol.View({ + * import CanvasMap from 'ol/CanvasMap'; + * import TileLayer from 'ol/layer/Tile'; + * import OSM from 'ol/source/OSM'; + * import View from 'ol/View'; + * + * var map = new CanvasMap({ + * view: new View({ * center: [0, 0], * zoom: 1 * }), * layers: [ - * new ol.layer.Tile({ - * source: new ol.source.OSM() + * new TileLayer({ + * source: new OSM() * }) * ], * target: 'map' * }); * - * The above snippet creates a map using a {@link ol.layer.Tile} to display - * {@link ol.source.OSM} OSM data and render it to a DOM element with the - * id `map`. + * The above snippet creates a map using a {@link module:ol/layer/Tile~Tile} to + * display {@link module:ol/source/OSM~OSM} OSM data and render it to a DOM + * element with the id `map`. * * The constructor places a viewport container (with CSS class name * `ol-viewport`) in the target element (see `getViewport()`), and then two * further elements within the viewport: one with CSS class name * `ol-overlaycontainer-stopevent` for controls and some overlays, and one with * CSS class name `ol-overlaycontainer` for other overlays (see the `stopEvent` - * option of {@link ol.Overlay} for the difference). The map itself is placed in - * a further element within the viewport. + * option of {@link module:ol/Overlay~Overlay} for the difference). The map + * itself is placed in a further element within the viewport. * - * Layers are stored as a `ol.Collection` in layerGroups. A top-level group is - * provided by the library. This is what is accessed by `getLayerGroup` and - * `setLayerGroup`. Layers entered in the options are added to this group, and - * `addLayer` and `removeLayer` change the layer collection in the group. - * `getLayers` is a convenience function for `getLayerGroup().getLayers()`. - * Note that `ol.layer.Group` is a subclass of `ol.layer.Base`, so layers - * entered in the options or added with `addLayer` can be groups, which can - * contain further groups, and so on. + * Layers are stored as a {@link module:ol/Collection~Collection} in + * layerGroups. A top-level group is provided by the library. This is what is + * accessed by `getLayerGroup` and `setLayerGroup`. Layers entered in the + * options are added to this group, and `addLayer` and `removeLayer` change the + * layer collection in the group. `getLayers` is a convenience function for + * `getLayerGroup().getLayers()`. + * Note that {@link module:ol/layer/Group~Group} is a subclass of + * {@link module:ol/layer/Base~Base}, so layers entered in the options or added + * with `addLayer` can be groups, which can contain further groups, and so on. * * @constructor - * @extends {ol.PluggableMap} - * @param {olx.MapOptions} options Map options. - * @fires ol.MapBrowserEvent - * @fires ol.MapEvent - * @fires ol.render.Event#postcompose - * @fires ol.render.Event#precompose + * @extends {module:ol/PluggableMap~PluggableMap} + * @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 CanvasMap = function(options) { diff --git a/src/ol/Collection.js b/src/ol/Collection.js index a713fc4851..760af21ebf 100644 --- a/src/ol/Collection.js +++ b/src/ol/Collection.js @@ -25,7 +25,7 @@ const Property = { * @constructor * @extends {module:ol/events/Event~Event} * @implements {oli.CollectionEvent} - * @param {module:ol/CollectionEventType} type Type. + * @param {module:ol/CollectionEventType~CollectionEventType} type Type. * @param {*=} opt_element Element. */ export const CollectionEvent = function(type, opt_element) { diff --git a/src/ol/CollectionEventType.js b/src/ol/CollectionEventType.js index a3f93ae83b..58ee49c827 100644 --- a/src/ol/CollectionEventType.js +++ b/src/ol/CollectionEventType.js @@ -8,13 +8,13 @@ export default { /** * Triggered when an item is added to the collection. - * @event ol.CollectionEvent#add + * @event module:ol/CollectionEvent~CollectionEvent#add * @api */ ADD: 'add', /** * Triggered when an item is removed from the collection. - * @event ol.CollectionEvent#remove + * @event module:ol/CollectionEvent~CollectionEvent#remove * @api */ REMOVE: 'remove' diff --git a/src/ol/Feature.js b/src/ol/Feature.js index 8cf65df0c7..ebe63ccf5f 100644 --- a/src/ol/Feature.js +++ b/src/ol/Feature.js @@ -18,7 +18,7 @@ import Style from './style/Style.js'; * Features can be styled individually with `setStyle`; otherwise they use the * style of their vector layer. * - * Note that attribute properties are set as {@link ol.Object} properties on + * Note that attribute properties are set as {@link module:ol/Object~Object} properties on * the feature object, so they are observable, and have get/set accessors. * * Typically, a feature has a single geometry property. You can set the @@ -30,9 +30,14 @@ import Style from './style/Style.js'; * property associated with the geometry for the feature. For example: * * ```js - * var feature = new ol.Feature({ - * geometry: new ol.geom.Polygon(polyCoords), - * labelPoint: new ol.geom.Point(labelCoords), + * + * import Feature from 'ol/Feature'; + * import Polygon from 'ol/geom/Polygon'; + * import Point from 'ol/geom/Point'; + * + * var feature = new Feature({ + * geometry: new Polygon(polyCoords), + * labelPoint: new Point(labelCoords), * name: 'My Polygon' * }); * @@ -47,11 +52,11 @@ import Style from './style/Style.js'; * ``` * * @constructor - * @extends {ol.Object} - * @param {ol.geom.Geometry|Object.=} opt_geometryOrProperties - * You may pass a Geometry object directly, or an object literal - * containing properties. If you pass an object literal, you may - * include a Geometry associated with a `geometry` key. + * @extends {module:ol/Object~Object} + * @param {module:ol/geom/Geometry~Geometry|Object.=} opt_geometryOrProperties + * You may pass a Geometry object directly, or an object literal containing + * properties. If you pass an object literal, you may include a Geometry + * associated with a `geometry` key. * @api */ const Feature = function(opt_geometryOrProperties) { @@ -73,19 +78,19 @@ const Feature = function(opt_geometryOrProperties) { /** * User provided style. * @private - * @type {ol.style.Style|Array.|ol.StyleFunction} + * @type {module:ol/style/Style~Geometry|Array.|module:ol/style~StyleFunction} */ this.style_ = null; /** * @private - * @type {ol.StyleFunction|undefined} + * @type {module:ol/style~StyleFunction|undefined} */ this.styleFunction_ = undefined; /** * @private - * @type {?ol.EventsKey} + * @type {?module:ol/events~EventsKey} */ this.geometryChangeKey_ = null; @@ -112,7 +117,7 @@ inherits(Feature, BaseObject); /** * Clone this feature. If the original feature has a geometry it * is also cloned. The feature id is not set in the clone. - * @return {ol.Feature} The clone. + * @return {module:ol/Feature~Feature} The clone. * @api */ Feature.prototype.clone = function() { @@ -133,13 +138,13 @@ Feature.prototype.clone = function() { /** * Get the feature's default geometry. A feature may have any number of named * geometries. The "default" geometry (the one that is rendered by default) is - * set when calling {@link ol.Feature#setGeometry}. - * @return {ol.geom.Geometry|undefined} The default geometry for the feature. + * set when calling {@link module:ol/Feature~Feature#setGeometry}. + * @return {module:ol/geom/Geometry~Geometry|undefined} The default geometry for the feature. * @api * @observable */ Feature.prototype.getGeometry = function() { - return /** @type {ol.geom.Geometry|undefined} */ ( + return /** @type {module:ol/geom/Geometry~Geometry|undefined} */ ( this.get(this.geometryName_)); }; @@ -147,7 +152,7 @@ Feature.prototype.getGeometry = function() { /** * Get the feature identifier. This is a stable identifier for the feature and * is either set when reading data from a remote source or set explicitly by - * calling {@link ol.Feature#setId}. + * calling {@link module:ol/Feature~Feature#setId}. * @return {number|string|undefined} Id. * @api */ @@ -170,8 +175,8 @@ Feature.prototype.getGeometryName = function() { /** * Get the feature's style. Will return what was provided to the - * {@link ol.Feature#setStyle} method. - * @return {ol.style.Style|Array.|ol.StyleFunction} The feature style. + * {@link module:ol/Feature~Feature#setStyle} method. + * @return {module:ol/style/Style~Geometry|Array.|module:ol/style~StyleFunction} The feature style. * @api */ Feature.prototype.getStyle = function() { @@ -181,7 +186,7 @@ Feature.prototype.getStyle = function() { /** * Get the feature's style function. - * @return {ol.StyleFunction|undefined} Return a function + * @return {module:ol/style~StyleFunction|undefined} Return a function * representing the current style of this feature. * @api */ @@ -217,8 +222,8 @@ Feature.prototype.handleGeometryChanged_ = function() { /** * Set the default geometry for the feature. This will update the property - * with the name returned by {@link ol.Feature#getGeometryName}. - * @param {ol.geom.Geometry|undefined} geometry The new geometry. + * with the name returned by {@link module:ol/Feature~Feature#getGeometryName}. + * @param {module:ol/geom/Geometry~Geometry|undefined} geometry The new geometry. * @api * @observable */ @@ -231,9 +236,9 @@ Feature.prototype.setGeometry = function(geometry) { * Set the style for the feature. This can be a single style object, an array * of styles, or a function that takes a resolution and returns an array of * styles. If it is `null` the feature has no style (a `null` style). - * @param {ol.style.Style|Array.|ol.StyleFunction} style Style for this feature. + * @param {module:ol/style/Style~Geometry|Array.|module:ol/style~StyleFunction} style Style for this feature. * @api - * @fires ol.events.Event#event:change + * @fires module:ol/events/Event~Event#event:change */ Feature.prototype.setStyle = function(style) { this.style_ = style; @@ -245,11 +250,11 @@ Feature.prototype.setStyle = function(style) { /** * Set the feature id. The feature id is considered stable and may be used when * requesting features or comparing identifiers returned from a remote source. - * The feature id can be used with the {@link ol.source.Vector#getFeatureById} - * method. + * The feature id can be used with the + * {@link module:ol/source/Vector~Vector#getFeatureById} method. * @param {number|string|undefined} id The feature id. * @api - * @fires ol.events.Event#event:change + * @fires module:ol/events/Event~Event#event:change */ Feature.prototype.setId = function(id) { this.id_ = id; @@ -259,7 +264,7 @@ Feature.prototype.setId = function(id) { /** * Set the property name to be used when getting the feature's default geometry. - * When calling {@link ol.Feature#getGeometry}, the value of the property with + * When calling {@link module:ol/Feature~Feature#getGeometry}, the value of the property with * this name will be returned. * @param {string} name The property name of the default geometry. * @api @@ -278,25 +283,25 @@ Feature.prototype.setGeometryName = function(name) { /** * Convert the provided object into a feature style function. Functions passed - * through unchanged. Arrays of ol.style.Style or single style objects wrapped + * through unchanged. Arrays of module:ol/style/Style~Geometry or single style objects wrapped * in a new feature style function. - * @param {ol.StyleFunction|!Array.|!ol.style.Style} obj + * @param {module:ol/style~StyleFunction|!Array.|!module:ol/style/Style~Geometry} obj * A feature style function, a single style, or an array of styles. - * @return {ol.StyleFunction} A style function. + * @return {module:ol/style~StyleFunction} A style function. */ export function createStyleFunction(obj) { if (typeof obj === 'function') { return obj; } else { /** - * @type {Array.} + * @type {Array.} */ let styles; if (Array.isArray(obj)) { styles = obj; } else { assert(obj instanceof Style, - 41); // Expected an `ol.style.Style` or an array of `ol.style.Style` + 41); // Expected an `module:ol/style/Style~Geometry` or an array of `module:ol/style/Style~Geometry` styles = [obj]; } return function() { diff --git a/src/ol/Geolocation.js b/src/ol/Geolocation.js index 2f82079d81..780bffd6e8 100644 --- a/src/ol/Geolocation.js +++ b/src/ol/Geolocation.js @@ -18,7 +18,7 @@ import {get as getProjection, getTransformFromProjections, identityTransform} fr * 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 + * @property {module:ol/proj~ProjectionLike} [projection] The projection the position * is reported in. */ @@ -58,13 +58,13 @@ const Geolocation = function(opt_options) { /** * The unprojected (EPSG:4326) device position. * @private - * @type {module:ol/types~Coordinate} + * @type {module:ol/coordinate~Coordinate} */ this.position_ = null; /** * @private - * @type {module:ol/types~TransformFunction} + * @type {module:ol/proj~TransformFunction} */ this.transform_ = identityTransform; @@ -247,13 +247,13 @@ Geolocation.prototype.getHeading = function() { /** * Get the position of the device. - * @return {module:ol/types~Coordinate|undefined} The current position of the device reported + * @return {module:ol/coordinate~Coordinate|undefined} The current position of the device reported * in the current projection. * @observable * @api */ Geolocation.prototype.getPosition = function() { - return /** @type {module:ol/types~Coordinate|undefined} */ (this.get(GeolocationProperty.POSITION)); + return /** @type {module:ol/coordinate~Coordinate|undefined} */ (this.get(GeolocationProperty.POSITION)); }; @@ -308,7 +308,7 @@ Geolocation.prototype.getTrackingOptions = function() { /** * Set the projection to use for transforming the coordinates. - * @param {module:ol/types~ProjectionLike} projection The projection the position is + * @param {module:ol/proj~ProjectionLike} projection The projection the position is * reported in. * @observable * @api diff --git a/src/ol/Graticule.js b/src/ol/Graticule.js index abb4c37c9b..ba9518d977 100644 --- a/src/ol/Graticule.js +++ b/src/ol/Graticule.js @@ -122,7 +122,7 @@ const Graticule = function(opt_options) { this.map_ = null; /** - * @type {?module:ol/types~EventsKey} + * @type {?module:ol/events~EventsKey} * @private */ this.postcomposeListenerKey_ = null; @@ -211,19 +211,19 @@ const Graticule = function(opt_options) { this.strokeStyle_ = options.strokeStyle !== undefined ? options.strokeStyle : DEFAULT_STROKE_STYLE; /** - * @type {module:ol/types~TransformFunction|undefined} + * @type {module:ol/proj~TransformFunction|undefined} * @private */ this.fromLonLatTransform_ = undefined; /** - * @type {module:ol/types~TransformFunction|undefined} + * @type {module:ol/proj~TransformFunction|undefined} * @private */ this.toLonLatTransform_ = undefined; /** - * @type {module:ol/types~Coordinate} + * @type {module:ol/coordinate~Coordinate} * @private */ this.projectionCenterLonLat_ = null; @@ -322,7 +322,7 @@ const Graticule = function(opt_options) { * @param {number} minLat Minimal latitude. * @param {number} maxLat Maximal latitude. * @param {number} squaredTolerance Squared tolerance. - * @param {module:ol/types~Extent} extent Extent. + * @param {module:ol/extent~Extent} extent Extent. * @param {number} index Index. * @return {number} Index. * @private @@ -344,7 +344,7 @@ Graticule.prototype.addMeridian_ = function(lon, minLat, maxLat, squaredToleranc /** * @param {module:ol/geom/LineString~LineString} lineString Meridian - * @param {module:ol/types~Extent} extent Extent. + * @param {module:ol/extent~Extent} extent Extent. * @param {number} index Index. * @return {module:ol/geom/Point~Point} Meridian point. * @private @@ -369,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 {module:ol/types~Extent} extent Extent. + * @param {module:ol/extent~Extent} extent Extent. * @param {number} index Index. * @return {number} Index. * @private @@ -392,7 +392,7 @@ Graticule.prototype.addParallel_ = function(lat, minLon, maxLon, squaredToleranc /** * @param {module:ol/geom/LineString~LineString} lineString Parallels. - * @param {module:ol/types~Extent} extent Extent. + * @param {module:ol/extent~Extent} extent Extent. * @param {number} index Index. * @return {module:ol/geom/Point~Point} Parallel point. * @private @@ -413,8 +413,8 @@ Graticule.prototype.getParallelPoint_ = function(lineString, extent, index) { /** - * @param {module:ol/types~Extent} extent Extent. - * @param {module:ol/types~Coordinate} center Center. + * @param {module:ol/extent~Extent} extent Extent. + * @param {module:ol/coordinate~Coordinate} center Center. * @param {number} resolution Resolution. * @param {number} squaredTolerance Squared tolerance. * @private diff --git a/src/ol/Image.js b/src/ol/Image.js index 1f97188232..d55426a6cd 100644 --- a/src/ol/Image.js +++ b/src/ol/Image.js @@ -8,15 +8,35 @@ import {listenOnce, unlistenByKey} from './events.js'; import EventType from './events/EventType.js'; import {getHeight} from './extent.js'; + +/** + * A function that takes an {@link module:ol/Image~Image} for the image and a + * `{string}` for the src as arguments. It is supposed to make it so the + * underlying image {@link module:ol/Image~Image#getImage} is assigned the + * content specified by the src. If not specified, the default is + * + * function(image, src) { + * image.getImage().src = src; + * } + * + * Providing a custom `imageLoadFunction` can be useful to load images with + * post requests or - in general - through XHR requests, where the src of the + * image element would be set to a data URI when the content is loaded. + * + * @typedef {function(module:ol/Image~Image, string)} LoadFunction + * @api + */ + + /** * @constructor - * @extends {ol.ImageBase} - * @param {ol.Extent} extent Extent. + * @extends {module:ol/ImageBase~ImageBase} + * @param {module:ol/extent~Extent} extent Extent. * @param {number|undefined} resolution Resolution. * @param {number} pixelRatio Pixel ratio. * @param {string} src Image source URI. * @param {?string} crossOrigin Cross origin. - * @param {ol.ImageLoadFunctionType} imageLoadFunction Image load function. + * @param {module:ol/Image~LoadFunction} imageLoadFunction Image load function. */ const ImageWrapper = function(extent, resolution, pixelRatio, src, crossOrigin, imageLoadFunction) { @@ -39,19 +59,19 @@ const ImageWrapper = function(extent, resolution, pixelRatio, src, crossOrigin, /** * @private - * @type {Array.} + * @type {Array.} */ this.imageListenerKeys_ = null; /** * @protected - * @type {ol.ImageState} + * @type {module:ol/ImageState~ImageState} */ this.state = ImageState.IDLE; /** * @private - * @type {ol.ImageLoadFunctionType} + * @type {module:ol/Image~LoadFunction} */ this.imageLoadFunction_ = imageLoadFunction; diff --git a/src/ol/ImageBase.js b/src/ol/ImageBase.js index d4bb8f1e88..272f9f879b 100644 --- a/src/ol/ImageBase.js +++ b/src/ol/ImageBase.js @@ -8,11 +8,11 @@ import EventType from './events/EventType.js'; /** * @constructor * @abstract - * @extends {ol.events.EventTarget} - * @param {ol.Extent} extent Extent. + * @extends {module:ol/events/EventTarget~EventTarget} + * @param {module:ol/extent~Extent} extent Extent. * @param {number|undefined} resolution Resolution. * @param {number} pixelRatio Pixel ratio. - * @param {ol.ImageState} state State. + * @param {module:ol/ImageState~ImageState} state State. */ const ImageBase = function(extent, resolution, pixelRatio, state) { @@ -20,7 +20,7 @@ const ImageBase = function(extent, resolution, pixelRatio, state) { /** * @protected - * @type {ol.Extent} + * @type {module:ol/extent~Extent} */ this.extent = extent; @@ -38,7 +38,7 @@ const ImageBase = function(extent, resolution, pixelRatio, state) { /** * @protected - * @type {ol.ImageState} + * @type {module:ol/ImageState~ImageState} */ this.state = state; @@ -56,7 +56,7 @@ ImageBase.prototype.changed = function() { /** - * @return {ol.Extent} Extent. + * @return {module:ol/extent~Extent} Extent. */ ImageBase.prototype.getExtent = function() { return this.extent; @@ -87,7 +87,7 @@ ImageBase.prototype.getResolution = function() { /** - * @return {ol.ImageState} State. + * @return {module:ol/ImageState~ImageState} State. */ ImageBase.prototype.getState = function() { return this.state; diff --git a/src/ol/ImageCanvas.js b/src/ol/ImageCanvas.js index 457caaaeff..a975d3640d 100644 --- a/src/ol/ImageCanvas.js +++ b/src/ol/ImageCanvas.js @@ -5,21 +5,32 @@ import {inherits} from './index.js'; import ImageBase from './ImageBase.js'; import ImageState from './ImageState.js'; + +/** + * 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. + * If any error occurs during drawing, the "done" callback should be called with + * that error. + * + * @typedef {function(function(Error))} Loader + */ + + /** * @constructor - * @extends {ol.ImageBase} - * @param {ol.Extent} extent Extent. + * @extends {module:ol/ImageBase~ImageBase} + * @param {module:ol/extent~Extent} extent Extent. * @param {number} resolution Resolution. * @param {number} pixelRatio Pixel ratio. * @param {HTMLCanvasElement} canvas Canvas. - * @param {ol.ImageCanvasLoader=} opt_loader Optional loader function to + * @param {module:ol/ImageCanvas~Loader=} opt_loader Optional loader function to * support asynchronous canvas drawing. */ const ImageCanvas = function(extent, resolution, pixelRatio, canvas, opt_loader) { /** * Optional canvas loader function. - * @type {?ol.ImageCanvasLoader} + * @type {?module:ol/ImageCanvas~Loader} * @private */ this.loader_ = opt_loader !== undefined ? opt_loader : null; diff --git a/src/ol/ImageTile.js b/src/ol/ImageTile.js index e22719a3f1..4449738e0f 100644 --- a/src/ol/ImageTile.js +++ b/src/ol/ImageTile.js @@ -10,13 +10,13 @@ import EventType from './events/EventType.js'; /** * @constructor - * @extends {ol.Tile} - * @param {ol.TileCoord} tileCoord Tile coordinate. - * @param {ol.TileState} state State. + * @extends {module:ol/Tile~Tile} + * @param {module:ol/tilecoord~TileCoord} tileCoord Tile coordinate. + * @param {module:ol/TileState~TileState} state State. * @param {string} src Image source URI. * @param {?string} crossOrigin Cross origin. - * @param {ol.TileLoadFunctionType} tileLoadFunction Tile load function. - * @param {olx.TileOptions=} opt_options Tile options. + * @param {module:ol/Tile~LoadFunction} tileLoadFunction Tile load function. + * @param {module:ol/Tile~Options=} opt_options Tile options. */ const ImageTile = function(tileCoord, state, src, crossOrigin, tileLoadFunction, opt_options) { @@ -47,13 +47,13 @@ const ImageTile = function(tileCoord, state, src, crossOrigin, tileLoadFunction, /** * @private - * @type {Array.} + * @type {Array.} */ this.imageListenerKeys_ = null; /** * @private - * @type {ol.TileLoadFunctionType} + * @type {module:ol/Tile~LoadFunction} */ this.tileLoadFunction_ = tileLoadFunction; diff --git a/src/ol/Map.js b/src/ol/Map.js index 50035aeb57..09c5197f2b 100644 --- a/src/ol/Map.js +++ b/src/ol/Map.js @@ -41,47 +41,53 @@ registerMultiple(PluginType.LAYER_RENDERER, [ * The map is the core component of OpenLayers. For a map to render, a view, * one or more layers, and a target container are needed: * + * import Map from 'ol/Map'; + * import View from 'ol/View'; + * import TileLayer from 'ol/layer/Tile'; + * import OSM from 'ol/source/OSM'; + * * var map = new Map({ - * view: new ol.View({ + * view: new View({ * center: [0, 0], * zoom: 1 * }), * layers: [ - * new ol.layer.Tile({ - * source: new ol.source.OSM() + * new TileLayer({ + * source: new OSM() * }) * ], * target: 'map' * }); * - * The above snippet creates a map using a {@link ol.layer.Tile} to display - * {@link ol.source.OSM} OSM data and render it to a DOM element with the - * id `map`. + * The above snippet creates a map using a {@link module:ol/layer/Tile~Tile} to + * display {@link module:ol/source/OSM~OSM} OSM data and render it to a DOM + * element with the id `map`. * * The constructor places a viewport container (with CSS class name * `ol-viewport`) in the target element (see `getViewport()`), and then two * further elements within the viewport: one with CSS class name * `ol-overlaycontainer-stopevent` for controls and some overlays, and one with * CSS class name `ol-overlaycontainer` for other overlays (see the `stopEvent` - * option of {@link ol.Overlay} for the difference). The map itself is placed in - * a further element within the viewport. + * option of {@link module:ol/Overlay~Overlay} for the difference). The map + * itself is placed in a further element within the viewport. * - * Layers are stored as a `ol.Collection` in layerGroups. A top-level group is - * provided by the library. This is what is accessed by `getLayerGroup` and - * `setLayerGroup`. Layers entered in the options are added to this group, and - * `addLayer` and `removeLayer` change the layer collection in the group. - * `getLayers` is a convenience function for `getLayerGroup().getLayers()`. - * Note that `ol.layer.Group` is a subclass of `ol.layer.Base`, so layers - * entered in the options or added with `addLayer` can be groups, which can - * contain further groups, and so on. + * Layers are stored as a {@link module:ol/Collection~Collection} in + * layerGroups. A top-level group is provided by the library. This is what is + * accessed by `getLayerGroup` and `setLayerGroup`. Layers entered in the + * options are added to this group, and `addLayer` and `removeLayer` change the + * layer collection in the group. `getLayers` is a convenience function for + * `getLayerGroup().getLayers()`. Note that {@link module:ol/layer/Group~Group} + * is a subclass of {@link module:ol/layer/Base~Base}, so layers entered in the + * options or added with `addLayer` can be groups, which can contain further + * groups, and so on. * * @constructor - * @extends {ol.PluggableMap} - * @param {olx.MapOptions} options Map options. - * @fires ol.MapBrowserEvent - * @fires ol.MapEvent - * @fires ol.render.Event#postcompose - * @fires ol.render.Event#precompose + * @extends {module:ol/PluggableMap~PluggableMap} + * @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 Map = function(options) { diff --git a/src/ol/MapBrowserEvent.js b/src/ol/MapBrowserEvent.js index bc8d7ce8b8..39c8a7abd7 100644 --- a/src/ol/MapBrowserEvent.js +++ b/src/ol/MapBrowserEvent.js @@ -7,13 +7,13 @@ import MapEvent from './MapEvent.js'; /** * @classdesc * Events emitted as map browser events are instances of this type. - * See {@link ol.Map} for which events trigger a map browser event. + * See {@link module:ol/Map~Map} for which events trigger a map browser event. * * @constructor - * @extends {ol.MapEvent} + * @extends {module:ol/MapEvent~MapEvent} * @implements {oli.MapBrowserEvent} * @param {string} type Event type. - * @param {ol.PluggableMap} map Map. + * @param {module:ol/PluggableMap~PluggableMap} map Map. * @param {Event} browserEvent Browser event. * @param {boolean=} opt_dragging Is the map currently being dragged? * @param {?olx.FrameState=} opt_frameState Frame state. @@ -32,14 +32,14 @@ const MapBrowserEvent = function(type, map, browserEvent, opt_dragging, opt_fram /** * The map pixel relative to the viewport corresponding to the original browser event. - * @type {ol.Pixel} + * @type {module:ol~Pixel} * @api */ this.pixel = map.getEventPixel(browserEvent); /** * The coordinate in view projection corresponding to the original browser event. - * @type {ol.Coordinate} + * @type {module:ol/coordinate~Coordinate} * @api */ this.coordinate = map.getCoordinateFromPixel(this.pixel); diff --git a/src/ol/MapBrowserEventHandler.js b/src/ol/MapBrowserEventHandler.js index aaf905c765..289c01afb0 100644 --- a/src/ol/MapBrowserEventHandler.js +++ b/src/ol/MapBrowserEventHandler.js @@ -11,10 +11,12 @@ import PointerEventType from './pointer/EventType.js'; import PointerEventHandler from './pointer/PointerEventHandler.js'; /** - * @param {ol.PluggableMap} map The map with the viewport to listen to events on. - * @param {number|undefined} moveTolerance The minimal distance the pointer must travel to trigger a move. + * @param {module:ol/PluggableMap~PluggableMap} map The map with the viewport to + * listen to events on. + * @param {number=} moveTolerance The minimal distance the pointer must travel + * to trigger a move. * @constructor - * @extends {ol.events.EventTarget} + * @extends {module:ol/events/EventTarget~EventTarget} */ const MapBrowserEventHandler = function(map, moveTolerance) { @@ -22,7 +24,7 @@ const MapBrowserEventHandler = function(map, moveTolerance) { /** * This is the element that we will listen to the real events on. - * @type {ol.PluggableMap} + * @type {module:ol/PluggableMap~PluggableMap} * @private */ this.map_ = map; @@ -40,7 +42,7 @@ const MapBrowserEventHandler = function(map, moveTolerance) { this.dragging_ = false; /** - * @type {!Array.} + * @type {!Array.} * @private */ this.dragListenerKeys_ = []; @@ -55,7 +57,7 @@ const MapBrowserEventHandler = function(map, moveTolerance) { /** * The most recent "down" type event (or null if none have occurred). * Set on pointerdown. - * @type {ol.pointer.PointerEvent} + * @type {module:ol/pointer/PointerEvent~PointerEvent} * @private */ this.down_ = null; @@ -78,7 +80,7 @@ const MapBrowserEventHandler = function(map, moveTolerance) { * Event handler which generates pointer events for * the viewport element. * - * @type {ol.pointer.PointerEventHandler} + * @type {module:ol/pointer/PointerEventHandler~PointerEventHandler} * @private */ this.pointerEventHandler_ = new PointerEventHandler(element); @@ -87,13 +89,13 @@ const MapBrowserEventHandler = function(map, moveTolerance) { * Event handler which generates pointer events for * the document (used when dragging). * - * @type {ol.pointer.PointerEventHandler} + * @type {module:ol/pointer/PointerEventHandler~PointerEventHandler} * @private */ this.documentPointerEventHandler_ = null; /** - * @type {?ol.EventsKey} + * @type {?module:ol/events~EventsKey} * @private */ this.pointerdownListenerKey_ = listen(this.pointerEventHandler_, @@ -101,7 +103,7 @@ const MapBrowserEventHandler = function(map, moveTolerance) { this.handlePointerDown_, this); /** - * @type {?ol.EventsKey} + * @type {?module:ol/events~EventsKey} * @private */ this.relayedListenerKey_ = listen(this.pointerEventHandler_, @@ -114,7 +116,8 @@ inherits(MapBrowserEventHandler, EventTarget); /** - * @param {ol.pointer.PointerEvent} pointerEvent Pointer event. + * @param {module:ol/pointer/PointerEvent~PointerEvent} pointerEvent Pointer + * event. * @private */ MapBrowserEventHandler.prototype.emulateClick_ = function(pointerEvent) { @@ -143,7 +146,8 @@ MapBrowserEventHandler.prototype.emulateClick_ = function(pointerEvent) { /** * Keeps track on how many pointers are currently active. * - * @param {ol.pointer.PointerEvent} pointerEvent Pointer event. + * @param {module:ol/pointer/PointerEvent~PointerEvent} pointerEvent Pointer + * event. * @private */ MapBrowserEventHandler.prototype.updateActivePointers_ = function(pointerEvent) { @@ -160,7 +164,8 @@ MapBrowserEventHandler.prototype.updateActivePointers_ = function(pointerEvent) /** - * @param {ol.pointer.PointerEvent} pointerEvent Pointer event. + * @param {module:ol/pointer/PointerEvent~PointerEvent} pointerEvent Pointer + * event. * @private */ MapBrowserEventHandler.prototype.handlePointerUp_ = function(pointerEvent) { @@ -191,7 +196,8 @@ MapBrowserEventHandler.prototype.handlePointerUp_ = function(pointerEvent) { /** - * @param {ol.pointer.PointerEvent} pointerEvent Pointer event. + * @param {module:ol/pointer/PointerEvent~PointerEvent} pointerEvent Pointer + * event. * @return {boolean} If the left mouse button was pressed. * @private */ @@ -201,7 +207,8 @@ MapBrowserEventHandler.prototype.isMouseActionButton_ = function(pointerEvent) { /** - * @param {ol.pointer.PointerEvent} pointerEvent Pointer event. + * @param {module:ol/pointer/PointerEvent~PointerEvent} pointerEvent Pointer + * event. * @private */ MapBrowserEventHandler.prototype.handlePointerDown_ = function(pointerEvent) { @@ -249,7 +256,8 @@ MapBrowserEventHandler.prototype.handlePointerDown_ = function(pointerEvent) { /** - * @param {ol.pointer.PointerEvent} pointerEvent Pointer event. + * @param {module:ol/pointer/PointerEvent~PointerEvent} pointerEvent Pointer + * event. * @private */ MapBrowserEventHandler.prototype.handlePointerMove_ = function(pointerEvent) { @@ -275,7 +283,8 @@ MapBrowserEventHandler.prototype.handlePointerMove_ = function(pointerEvent) { /** * Wrap and relay a pointer event. Note that this requires that the type * string for the MapBrowserPointerEvent matches the PointerEvent type. - * @param {ol.pointer.PointerEvent} pointerEvent Pointer event. + * @param {module:ol/pointer/PointerEvent~PointerEvent} pointerEvent Pointer + * event. * @private */ MapBrowserEventHandler.prototype.relayEvent_ = function(pointerEvent) { @@ -286,7 +295,8 @@ MapBrowserEventHandler.prototype.relayEvent_ = function(pointerEvent) { /** - * @param {ol.pointer.PointerEvent} pointerEvent Pointer event. + * @param {module:ol/pointer/PointerEvent~PointerEvent} pointerEvent Pointer + * event. * @return {boolean} Is moving. * @private */ diff --git a/src/ol/MapBrowserEventType.js b/src/ol/MapBrowserEventType.js index 546572ea71..75e0d84c21 100644 --- a/src/ol/MapBrowserEventType.js +++ b/src/ol/MapBrowserEventType.js @@ -12,28 +12,28 @@ export default { /** * A true single click with no dragging and no double click. Note that this * event is delayed by 250 ms to ensure that it is not a double click. - * @event ol.MapBrowserEvent#singleclick + * @event module:ol/MapBrowserEvent~MapBrowserEvent#singleclick * @api */ SINGLECLICK: 'singleclick', /** * A click with no dragging. A double click will fire two of this. - * @event ol.MapBrowserEvent#click + * @event module:ol/MapBrowserEvent~MapBrowserEvent#click * @api */ CLICK: EventType.CLICK, /** * A true double click, with no dragging. - * @event ol.MapBrowserEvent#dblclick + * @event module:ol/MapBrowserEvent~MapBrowserEvent#dblclick * @api */ DBLCLICK: EventType.DBLCLICK, /** * Triggered when a pointer is dragged. - * @event ol.MapBrowserEvent#pointerdrag + * @event module:ol/MapBrowserEvent~MapBrowserEvent#pointerdrag * @api */ POINTERDRAG: 'pointerdrag', @@ -41,7 +41,7 @@ export default { /** * Triggered when a pointer is moved. Note that on touch devices this is * triggered when the map is panned, so is not the same as mousemove. - * @event ol.MapBrowserEvent#pointermove + * @event module:ol/MapBrowserEvent~MapBrowserEvent#pointermove * @api */ POINTERMOVE: 'pointermove', diff --git a/src/ol/MapBrowserPointerEvent.js b/src/ol/MapBrowserPointerEvent.js index e5a4a97bce..f11219e044 100644 --- a/src/ol/MapBrowserPointerEvent.js +++ b/src/ol/MapBrowserPointerEvent.js @@ -6,12 +6,13 @@ import MapBrowserEvent from './MapBrowserEvent.js'; /** * @constructor - * @extends {ol.MapBrowserEvent} + * @extends {module:ol/MapBrowserEvent~MapBrowserEvent} * @param {string} type Event type. - * @param {ol.PluggableMap} map Map. - * @param {ol.pointer.PointerEvent} pointerEvent Pointer event. + * @param {module:ol/PluggableMap~PluggableMap} map Map. + * @param {module:ol/pointer/PointerEvent~PointerEvent} pointerEvent Pointer + * event. * @param {boolean=} opt_dragging Is the map currently being dragged? - * @param {?olx.FrameState=} opt_frameState Frame state. + * @param {?module:ol/PluggableMap~FrameState=} opt_frameState Frame state. */ const MapBrowserPointerEvent = function(type, map, pointerEvent, opt_dragging, opt_frameState) { @@ -21,7 +22,7 @@ const MapBrowserPointerEvent = function(type, map, pointerEvent, opt_dragging, /** * @const - * @type {ol.pointer.PointerEvent} + * @type {module:ol/pointer/PointerEvent~PointerEvent} */ this.pointerEvent = pointerEvent; diff --git a/src/ol/MapEvent.js b/src/ol/MapEvent.js index af64662b1b..5aac317f48 100644 --- a/src/ol/MapEvent.js +++ b/src/ol/MapEvent.js @@ -7,14 +7,14 @@ import Event from './events/Event.js'; /** * @classdesc * Events emitted as map events are instances of this type. - * See {@link ol.Map} for which events trigger a map event. + * See {@link module:ol/Map~Map} for which events trigger a map event. * * @constructor - * @extends {ol.events.Event} + * @extends {module:ol/events/Event~Event} * @implements {oli.MapEvent} * @param {string} type Event type. - * @param {ol.PluggableMap} map Map. - * @param {?olx.FrameState=} opt_frameState Frame state. + * @param {module:ol/PluggableMap~PluggableMap} map Map. + * @param {?module:ol/PluggableMap~FrameState=} opt_frameState Frame state. */ const MapEvent = function(type, map, opt_frameState) { @@ -22,14 +22,14 @@ const MapEvent = function(type, map, opt_frameState) { /** * The map where the event occurred. - * @type {ol.PluggableMap} + * @type {module:ol/PluggableMap~PluggableMap} * @api */ this.map = map; /** * The frame state at the time of the event. - * @type {?olx.FrameState} + * @type {?module:ol/PluggableMap~FrameState} * @api */ this.frameState = opt_frameState !== undefined ? opt_frameState : null; diff --git a/src/ol/MapEventType.js b/src/ol/MapEventType.js index 8667a2cb58..0f25adf5b9 100644 --- a/src/ol/MapEventType.js +++ b/src/ol/MapEventType.js @@ -9,21 +9,21 @@ export default { /** * Triggered after a map frame is rendered. - * @event ol.MapEvent#postrender + * @event module:ol/MapEvent~MapEvent#postrender * @api */ POSTRENDER: 'postrender', /** * Triggered when the map starts moving. - * @event ol.MapEvent#movestart + * @event module:ol/MapEvent~MapEvent#movestart * @api */ MOVESTART: 'movestart', /** * Triggered after the map is moved. - * @event ol.MapEvent#moveend + * @event module:ol/MapEvent~MapEvent#moveend * @api */ MOVEEND: 'moveend' diff --git a/src/ol/Object.js b/src/ol/Object.js index 2a51192d43..f76e0632a9 100644 --- a/src/ol/Object.js +++ b/src/ol/Object.js @@ -10,16 +10,17 @@ import {assign} from './obj.js'; /** * @classdesc - * Events emitted by {@link ol.Object} instances are instances of this type. + * Events emitted by {@link module:ol/Object~Object} instances are instances of + * this type. * * @param {string} type The event type. * @param {string} key The property name. * @param {*} oldValue The old value for `key`. - * @extends {ol.events.Event} + * @extends {module:ol/events/Event~Event} * @implements {oli.Object.Event} * @constructor */ -const BaseObjectEvent = function(type, key, oldValue) { +const ObjectEvent = function(type, key, oldValue) { Event.call(this, type); /** @@ -38,7 +39,7 @@ const BaseObjectEvent = function(type, key, oldValue) { this.oldValue = oldValue; }; -inherits(BaseObjectEvent, Event); +inherits(ObjectEvent, Event); /** @@ -47,29 +48,30 @@ inherits(BaseObjectEvent, Event); * instantiated in apps. * Most non-trivial classes inherit from this. * - * This extends {@link ol.Observable} with observable properties, where each - * property is observable as well as the object as a whole. + * This extends {@link module:ol/Observable~Observable} with observable + * properties, where each property is observable as well as the object as a + * whole. * * Classes that inherit from this have pre-defined properties, to which you can * add your owns. The pre-defined properties are listed in this documentation as * 'Observable Properties', and have their own accessors; for example, - * {@link ol.Map} has a `target` property, accessed with `getTarget()` and - * changed with `setTarget()`. Not all properties are however settable. There - * are also general-purpose accessors `get()` and `set()`. For example, - * `get('target')` is equivalent to `getTarget()`. + * {@link module:ol/Map~Map} has a `target` property, accessed with + * `getTarget()` and changed with `setTarget()`. Not all properties are however + * settable. There are also general-purpose accessors `get()` and `set()`. For + * example, `get('target')` is equivalent to `getTarget()`. * * The `set` accessors trigger a change event, and you can monitor this by - * registering a listener. For example, {@link ol.View} has a `center` - * property, so `view.on('change:center', function(evt) {...});` would call the - * function whenever the value of the center property changes. Within the - * function, `evt.target` would be the view, so `evt.target.getCenter()` would - * return the new center. + * registering a listener. For example, {@link module:ol/View~View} has a + * `center` property, so `view.on('change:center', function(evt) {...});` would + * call the function whenever the value of the center property changes. Within + * the function, `evt.target` would be the view, so `evt.target.getCenter()` + * would return the new center. * * You can add your own observable properties with * `object.set('prop', 'value')`, and retrieve that with `object.get('prop')`. * You can listen for changes on that property value with * `object.on('change:prop', listener)`. You can get a list of all - * properties with {@link ol.Object#getProperties object.getProperties()}. + * properties with {@link module:ol/Object~Object#getProperties}. * * Note that the observable properties are separate from standard JS properties. * You can, for example, give your map object a title with @@ -81,18 +83,18 @@ inherits(BaseObjectEvent, Event); * object.unset('foo'). * * @constructor - * @extends {ol.Observable} + * @extends {module:ol/Observable~Observable} * @param {Object.=} opt_values An object with key-value pairs. - * @fires ol.Object.Event + * @fires module:ol/Object~ObjectEvent * @api */ const BaseObject = function(opt_values) { Observable.call(this); - // Call ol.getUid to ensure that the order of objects' ids is the same as - // the order in which they were created. This also helps to ensure that - // object properties are always added in the same order, which helps many - // JavaScript engines generate faster code. + // Call {@link module:ol~getUid} to ensure that the order of objects' ids is + // the same as the order in which they were created. This also helps to + // ensure that object properties are always added in the same order, which + // helps many JavaScript engines generate faster code. getUid(this); /** @@ -168,9 +170,9 @@ BaseObject.prototype.getProperties = function() { BaseObject.prototype.notify = function(key, oldValue) { let eventType; eventType = getChangeEventType(key); - this.dispatchEvent(new BaseObjectEvent(eventType, key, oldValue)); + this.dispatchEvent(new ObjectEvent(eventType, key, oldValue)); eventType = ObjectEventType.PROPERTYCHANGE; - this.dispatchEvent(new BaseObjectEvent(eventType, key, oldValue)); + this.dispatchEvent(new ObjectEvent(eventType, key, oldValue)); }; diff --git a/src/ol/ObjectEventType.js b/src/ol/ObjectEventType.js index 8ebcc9d293..2fc546c02b 100644 --- a/src/ol/ObjectEventType.js +++ b/src/ol/ObjectEventType.js @@ -8,7 +8,7 @@ export default { /** * Triggered when a property is changed. - * @event ol.Object.Event#propertychange + * @event module:ol/Object~Event#propertychange * @api */ PROPERTYCHANGE: 'propertychange' diff --git a/src/ol/Observable.js b/src/ol/Observable.js index 596ea0788e..caaeb99b7c 100644 --- a/src/ol/Observable.js +++ b/src/ol/Observable.js @@ -12,11 +12,11 @@ import EventType from './events/EventType.js'; * instantiated in apps. * An event target providing convenient methods for listener registration * and unregistration. A generic `change` event is always available through - * {@link ol.Observable#changed}. + * {@link module:ol/Observable~Observable#changed}. * * @constructor - * @extends {ol.events.EventTarget} - * @fires ol.events.Event + * @extends {module:ol/events/EventTarget~EventTarget} + * @fires module:ol/events/Event~Event * @struct * @api */ @@ -37,7 +37,7 @@ inherits(Observable, EventTarget); /** * Removes an event listener using the key returned by `on()` or `once()`. - * @param {ol.EventsKey|Array.} key The key returned by `on()` + * @param {module:ol/events~EventsKey|Array.} key The key returned by `on()` * or `once()` (or an array of keys). * @api */ @@ -47,7 +47,7 @@ export function unByKey(key) { unlistenByKey(key[i]); } } else { - unlistenByKey(/** @type {ol.EventsKey} */ (key)); + unlistenByKey(/** @type {module:ol/events~EventsKey} */ (key)); } } @@ -68,8 +68,8 @@ Observable.prototype.changed = function() { * Object with a `type` property. * * @param {{type: string, - * target: (EventTarget|ol.events.EventTarget|undefined)}|ol.events.Event| - * string} event Event object. + * target: (EventTarget|module:ol/events/EventTarget~EventTarget|undefined)}| + * module:ol/events/Event~Event|string} event Event object. * @function * @api */ @@ -91,7 +91,7 @@ Observable.prototype.getRevision = function() { * Listen for a certain type of event. * @param {string|Array.} type The event type or array of event types. * @param {function(?): ?} listener The listener function. - * @return {ol.EventsKey|Array.} Unique key for the listener. If + * @return {module:ol/events~EventsKey|Array.} Unique key for the listener. If * called with an array of event types as the first argument, the return * will be an array of keys. * @api @@ -114,7 +114,7 @@ Observable.prototype.on = function(type, listener) { * Listen once for a certain type of event. * @param {string|Array.} type The event type or array of event types. * @param {function(?): ?} listener The listener function. - * @return {ol.EventsKey|Array.} Unique key for the listener. If + * @return {module:ol/events~EventsKey|Array.} Unique key for the listener. If * called with an array of event types as the first argument, the return * will be an array of keys. * @api diff --git a/src/ol/Overlay.js b/src/ol/Overlay.js index b739ae480b..9f56dfd969 100644 --- a/src/ol/Overlay.js +++ b/src/ol/Overlay.js @@ -11,6 +11,57 @@ import {listen, unlistenByKey} from './events.js'; import {containsExtent} from './extent.js'; +/** + * @typedef {Object} OverlayOptions + * @property {number|string} [id] Set the overlay id. The overlay id can be used + * with the {@link module:ol/Map~Map#getOverlayById} method. + * @property {Element} [element] The overlay element. + * @property {Array.} [offset=[0, 0]] Offsets in pixels used when positioning + * the overlay. The first element in the + * array is the horizontal offset. A positive value shifts the overlay right. + * The second element in the array is the vertical offset. A positive value + * shifts the overlay down. + * @property {module:ol/coordinate~Coordinate~Coordinate} [position] The overlay position + * in map projection. + * @property {module:ol/OverlayPositioning~OverlayPositioning} [positioning='top-left'] Defines how + * the overlay is actually positioned with respect to its `position` property. + * Possible values are `'bottom-left'`, `'bottom-center'`, `'bottom-right'`, + * `'center-left'`, `'center-center'`, `'center-right'`, `'top-left'`, + * `'top-center'`, and `'top-right'`. + * @property {boolean} [stopEvent=true] Whether event propagation to the map + * viewport should be stopped. If `true` the overlay is placed in the same + * container as that of the controls (CSS class name + * `ol-overlaycontainer-stopevent`); if `false` it is placed in the container + * with CSS class name `ol-overlaycontainer`. + * @property {boolean} [insertFirst=true] Whether the overlay is inserted first + * in the overlay container, or appended. If the overlay is placed in the same + * container as that of the controls (see the `stopEvent` option) you will + * probably set `insertFirst` to `true` so the overlay is displayed below the + * controls. + * @property {boolean} [autoPan=false] If set to `true` the map is panned when + * calling `setPosition`, so that the overlay is entirely visible in the current + * viewport. + * @property {module:ol/Overlay~OverlayPanOptions} [autoPanAnimation] The + * animation options used to pan the overlay into view. This animation is only + * used when `autoPan` is enabled. A `duration` and `easing` may be provided to + * customize the animation. + * @property {number} [autoPanMargin=20] The margin (in pixels) between the + * overlay and the borders of the map when autopanning. + * @property {string} [className='ol-overlay-container ol-selectable'] CSS class + * name. + */ + + +/** + * @typedef {Object} OverlayPanOptions + * @property {number} [duration=1000] The duration of the animation in + * milliseconds. + * @property {function(number):number} [easing] The easing function to use. Can + * be one from {@link module:ol/easing} or a custom function. + * Default is {@link module:ol/easing~inAndOut}. + */ + + /** * @enum {string} * @protected @@ -27,21 +78,23 @@ const Property = { /** * @classdesc * An element to be displayed over the map and attached to a single map - * location. Like {@link ol.control.Control}, Overlays are visible widgets. - * Unlike Controls, they are not in a fixed position on the screen, but are tied - * to a geographical coordinate, so panning the map will move an Overlay but not - * a Control. + * location. Like {@link module:ol/control/Control~Control}, Overlays are + * visible widgets. Unlike Controls, they are not in a fixed position on the + * screen, but are tied to a geographical coordinate, so panning the map will + * move an Overlay but not a Control. * * Example: * - * var popup = new ol.Overlay({ + * import Overlay from 'ol/Overlay'; + * + * var popup = new Overlay({ * element: document.getElementById('popup') * }); * popup.setPosition(coordinate); * map.addOverlay(popup); * * @constructor - * @extends {ol.Object} + * @extends {module:ol/Object~Object} * @param {olx.OverlayOptions} options Overlay options. * @api */ @@ -121,7 +174,7 @@ const Overlay = function(options) { /** * @protected - * @type {?ol.EventsKey} + * @type {?module:ol/events~EventsKey} */ this.mapPostrenderListenerKey = null; @@ -152,7 +205,7 @@ const Overlay = function(options) { this.setOffset(options.offset !== undefined ? options.offset : [0, 0]); this.setPositioning(options.positioning !== undefined ? - /** @type {ol.OverlayPositioning} */ (options.positioning) : + /** @type {module:ol/OverlayPositioning~OverlayPositioning} */ (options.positioning) : OverlayPositioning.TOP_LEFT); if (options.position !== undefined) { @@ -187,12 +240,13 @@ Overlay.prototype.getId = function() { /** * Get the map associated with this overlay. - * @return {ol.PluggableMap|undefined} The map that the overlay is part of. + * @return {module:ol/PluggableMap~PluggableMap|undefined} The map that the + * overlay is part of. * @observable * @api */ Overlay.prototype.getMap = function() { - return /** @type {ol.PluggableMap|undefined} */ (this.get(Property.MAP)); + return /** @type {module:ol/PluggableMap~PluggableMap|undefined} */ (this.get(Property.MAP)); }; @@ -209,25 +263,25 @@ Overlay.prototype.getOffset = function() { /** * Get the current position of this overlay. - * @return {ol.Coordinate|undefined} The spatial point that the overlay is + * @return {module:ol/coordinate~Coordinate|undefined} The spatial point that the overlay is * anchored at. * @observable * @api */ Overlay.prototype.getPosition = function() { - return /** @type {ol.Coordinate|undefined} */ (this.get(Property.POSITION)); + return /** @type {module:ol/coordinate~Coordinate|undefined} */ (this.get(Property.POSITION)); }; /** * Get the current positioning of this overlay. - * @return {ol.OverlayPositioning} How the overlay is positioned + * @return {module:ol/OverlayPositioning~OverlayPositioning} How the overlay is positioned * relative to its point on the map. * @observable * @api */ Overlay.prototype.getPositioning = function() { - return /** @type {ol.OverlayPositioning} */ (this.get(Property.POSITIONING)); + return /** @type {module:ol/OverlayPositioning~OverlayPositioning} */ (this.get(Property.POSITIONING)); }; @@ -316,7 +370,8 @@ Overlay.prototype.setElement = function(element) { /** * Set the map to be associated with this overlay. - * @param {ol.PluggableMap|undefined} map The map that the overlay is part of. + * @param {module:ol/PluggableMap~PluggableMap|undefined} map The map that the + * overlay is part of. * @observable * @api */ @@ -339,7 +394,7 @@ Overlay.prototype.setOffset = function(offset) { /** * Set the position for this overlay. If the position is `undefined` the * overlay is hidden. - * @param {ol.Coordinate|undefined} position The spatial point that the overlay + * @param {module:ol/coordinate~Coordinate|undefined} position The spatial point that the overlay * is anchored at. * @observable * @api @@ -390,7 +445,7 @@ Overlay.prototype.panIntoView = function() { } if (delta[0] !== 0 || delta[1] !== 0) { - const center = /** @type {ol.Coordinate} */ (map.getView().getCenter()); + const center = /** @type {module:ol/coordinate~Coordinate} */ (map.getView().getCenter()); const centerPx = map.getPixelFromCoordinate(center); const newCenterPx = [ centerPx[0] + delta[0], @@ -410,8 +465,8 @@ Overlay.prototype.panIntoView = function() { /** * Get the extent of an element relative to the document * @param {Element|undefined} element The element. - * @param {ol.Size|undefined} size The size of the element. - * @return {ol.Extent} The extent. + * @param {module:ol/size~Size|undefined} size The size of the element. + * @return {module:ol/extent~Extent} The extent. * @protected */ Overlay.prototype.getRect = function(element, size) { @@ -429,7 +484,7 @@ Overlay.prototype.getRect = function(element, size) { /** * Set the positioning for this overlay. - * @param {ol.OverlayPositioning} positioning how the overlay is + * @param {module:ol/OverlayPositioning~OverlayPositioning} positioning how the overlay is * positioned relative to its point on the map. * @observable * @api @@ -471,8 +526,8 @@ Overlay.prototype.updatePixelPosition = function() { /** - * @param {ol.Pixel} pixel The pixel location. - * @param {ol.Size|undefined} mapSize The map size. + * @param {module:ol~Pixel} pixel The pixel location. + * @param {module:ol/size~Size|undefined} mapSize The map size. * @protected */ Overlay.prototype.updateRenderedPosition = function(pixel, mapSize) { diff --git a/src/ol/PluggableMap.js b/src/ol/PluggableMap.js index 1fc7cd0c3c..3617503080 100644 --- a/src/ol/PluggableMap.js +++ b/src/ol/PluggableMap.js @@ -31,6 +31,36 @@ import {DROP} from './structs/PriorityQueue.js'; import {create as createTransform, apply as applyTransform} from './transform.js'; +/** + * State of the current frame. Only `pixelRatio`, `time` and `viewState` should + * be used in applications. + * @typedef {Object} FrameState + * @property {number} pixelRatio The pixel ratio of the frame. + * @property {number} time The time when rendering of the frame was requested. + * @property {olx.ViewState} viewState The state of the current view. + * @property {boolean} animate + * @property {module:ol/transform~Transform} coordinateToPixelTransform + * @property {null|module:ol/extent~Extent} extent + * @property {module:ol/coordinate~Coordinate} focus + * @property {number} index + * @property {Object.} layerStates + * @property {Array.} postRenderFunctions + * @property {module:ol/size~Size} size + * @property {!Object.} skippedFeatureUids + * @property {module:ol/TileQueue~TileQueue} tileQueue + * @property {Object.>} usedTiles + * @property {Array.} viewHints + * @property {!Object.>} wantedTiles + */ + + +/** + * @typedef {function(module:ol/PluggableMap~PluggableMap, ?olx.FrameState): boolean} PostRenderFunction + */ + + /** * @typedef {Object} MapOptionsInternal * @property {module:ol/Collection~Collection.} [controls] @@ -157,13 +187,13 @@ const PluggableMap = function(options) { /** * @private - * @type {module:ol/types~Transform} + * @type {module:ol/transform~Transform} */ this.coordinateToPixelTransform_ = createTransform(); /** * @private - * @type {module:ol/types~Transform} + * @type {module:ol/transform~Transform} */ this.pixelToCoordinateTransform_ = createTransform(); @@ -182,25 +212,25 @@ const PluggableMap = function(options) { /** * The extent at the previous 'moveend' event. * @private - * @type {module:ol/types~Extent} + * @type {module:ol/extent~Extent} */ this.previousExtent_ = null; /** * @private - * @type {?module:ol/types~EventsKey} + * @type {?module:ol/events~EventsKey} */ this.viewPropertyListenerKey_ = null; /** * @private - * @type {?module:ol/types~EventsKey} + * @type {?module:ol/events~EventsKey} */ this.viewChangeListenerKey_ = null; /** * @private - * @type {Array.} + * @type {Array.} */ this.layerGroupPropertyListenerKeys_ = null; @@ -265,7 +295,7 @@ const PluggableMap = function(options) { /** * @private - * @type {Array.} + * @type {Array.} */ this.keyHandlerKeys_ = null; @@ -315,13 +345,13 @@ const PluggableMap = function(options) { /** * @private - * @type {module:ol/types~Coordinate} + * @type {module:ol/coordinate~Coordinate} */ this.focus_ = null; /** * @private - * @type {!Array.} + * @type {!Array.} */ this.postRenderFunctions_ = []; @@ -515,7 +545,7 @@ 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 {module:ol/types~Pixel} pixel Pixel. + * @param {module:ol~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 @@ -548,7 +578,7 @@ PluggableMap.prototype.forEachFeatureAtPixel = function(pixel, callback, opt_opt /** * Get all features that intersect a pixel on the viewport. - * @param {module:ol/types~Pixel} pixel Pixel. + * @param {module:ol~Pixel} pixel Pixel. * @param {olx.AtPixelOptions=} opt_options Optional options. * @return {Array.} The detected features or * `null` if none were found. @@ -569,7 +599,7 @@ 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 {module:ol/types~Pixel} pixel Pixel. + * @param {module:ol~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 module:ol/layer/Layer~Layer layer}, second argument is an array representing @@ -605,7 +635,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 {module:ol/types~Pixel} pixel Pixel. + * @param {module:ol~Pixel} pixel Pixel. * @param {olx.AtPixelOptions=} opt_options Optional options. * @return {boolean} Is there a feature at the given pixel? * @template U @@ -628,7 +658,7 @@ PluggableMap.prototype.hasFeatureAtPixel = function(pixel, opt_options) { /** * Returns the coordinate in view projection for a browser event. * @param {Event} event Event. - * @return {module:ol/types~Coordinate} Coordinate. + * @return {module:ol/coordinate~Coordinate} Coordinate. * @api */ PluggableMap.prototype.getEventCoordinate = function(event) { @@ -639,7 +669,7 @@ PluggableMap.prototype.getEventCoordinate = function(event) { /** * Returns the map pixel position for a browser event relative to the viewport. * @param {Event} event Event. - * @return {module:ol/types~Pixel} Pixel. + * @return {module:ol~Pixel} Pixel. * @api */ PluggableMap.prototype.getEventPixel = function(event) { @@ -686,8 +716,8 @@ PluggableMap.prototype.getTargetElement = function() { /** * Get the coordinate for a given pixel. This returns a coordinate in the * map view projection. - * @param {module:ol/types~Pixel} pixel Pixel position in the map viewport. - * @return {module:ol/types~Coordinate} The coordinate for the pixel position. + * @param {module:ol~Pixel} pixel Pixel position in the map viewport. + * @return {module:ol/coordinate~Coordinate} The coordinate for the pixel position. * @api */ PluggableMap.prototype.getCoordinateFromPixel = function(pixel) { @@ -774,8 +804,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 {module:ol/types~Coordinate} coordinate A map coordinate. - * @return {module:ol/types~Pixel} A pixel position in the map viewport. + * @param {module:ol/coordinate~Coordinate} coordinate A map coordinate. + * @return {module:ol~Pixel} A pixel position in the map viewport. * @api */ PluggableMap.prototype.getPixelFromCoordinate = function(coordinate) { @@ -799,12 +829,12 @@ PluggableMap.prototype.getRenderer = function() { /** * Get the size of this map. - * @return {module:ol/types~Size|undefined} The size in pixels of the map in the DOM. + * @return {module:ol/size~Size|undefined} The size in pixels of the map in the DOM. * @observable * @api */ PluggableMap.prototype.getSize = function() { - return /** @type {module:ol/types~Size|undefined} */ (this.get(MapProperty.SIZE)); + return /** @type {module:ol/size~Size|undefined} */ (this.get(MapProperty.SIZE)); }; @@ -857,7 +887,7 @@ PluggableMap.prototype.getOverlayContainerStopEvent = function() { /** * @param {module:ol/Tile~Tile} tile Tile. * @param {string} tileSourceKey Tile source key. - * @param {module:ol/types~Coordinate} tileCenter Tile center. + * @param {module:ol/coordinate~Coordinate} tileCenter Tile center. * @param {number} tileResolution Tile resolution. * @return {number} Tile priority. */ @@ -1277,7 +1307,7 @@ PluggableMap.prototype.setLayerGroup = function(layerGroup) { /** * Set the size of this map. - * @param {module:ol/types~Size|undefined} size The size in pixels of the map in the DOM. + * @param {module:ol/size~Size|undefined} size The size in pixels of the map in the DOM. * @observable * @api */ diff --git a/src/ol/Tile.js b/src/ol/Tile.js index 7399ccd868..a132a9c55b 100644 --- a/src/ol/Tile.js +++ b/src/ol/Tile.js @@ -7,16 +7,52 @@ import {easeIn} from './easing.js'; import EventTarget from './events/EventTarget.js'; import EventType from './events/EventType.js'; + +/** + * A function that takes an {@link module:ol/Tile~Tile} for the tile and a + * `{string}` for the url as arguments. + * + * @typedef {function(module:ol/Tile~Tile, string)} LoadFunction + * @api + */ + + +/** + * {@link module:ol/source/Tile~Tile} sources use a function of this type to get + * the url that provides a tile for a given tile coordinate. + * + * This function takes an {@link module:ol/tilecoord~TileCoord} for the tile + * coordinate, a `{number}` representing the pixel ratio and a + * {@link module:ol/proj/Projection~Projection} for the projection as arguments + * and returns a `{string}` representing the tile URL, or undefined if no tile + * should be requested for the passed tile coordinate. + * + * @typedef {function(module:ol/tilecoord~TileCoord, number, + * module:ol/proj/Projection~Projection): (string|undefined)} Type + * @api + */ + + +/** + * @typedef {Object} Options + * @property {number|undefined} transition A duration for tile opacity + * transitions. By default, tiles will render with an opacity transition that + * lasts 250 ms. To change the duration, pass a number in milliseconds. A + * duration of 0 disables the opacity transition. + * @api + */ + + /** * @classdesc * Base class for tiles. * * @constructor * @abstract - * @extends {ol.events.EventTarget} - * @param {ol.TileCoord} tileCoord Tile coordinate. - * @param {ol.TileState} state State. - * @param {olx.TileOptions=} opt_options Tile options. + * @extends {module:ol/events/EventTarget~EventTarget} + * @param {module:ol/tilecoord~TileCoord} tileCoord Tile coordinate. + * @param {module:ol/TileState~TileState} state State. + * @param {module:ol/Tile~Options=} opt_options Tile options. */ const Tile = function(tileCoord, state, opt_options) { EventTarget.call(this); @@ -24,13 +60,13 @@ const Tile = function(tileCoord, state, opt_options) { const options = opt_options ? opt_options : {}; /** - * @type {ol.TileCoord} + * @type {module:ol/tilecoord~TileCoord} */ this.tileCoord = tileCoord; /** * @protected - * @type {ol.TileState} + * @type {module:ol/TileState~TileState} */ this.state = state; @@ -38,7 +74,7 @@ const Tile = function(tileCoord, state, opt_options) { * An "interim" tile for this tile. The interim tile may be used while this * one is loading, for "smooth" transitions when changing params/dimensions * on the source. - * @type {ol.Tile} + * @type {module:ol/Tile~Tile} */ this.interimTile = null; @@ -88,7 +124,7 @@ Tile.prototype.getKey = function() { * Get the interim tile most suitable for rendering using the chain of interim * tiles. This corresponds to the most recent tile that has been loaded, if no * such tile exists, the original tile is returned. - * @return {!ol.Tile} Best tile for rendering. + * @return {!module:ol/Tile~Tile} Best tile for rendering. */ Tile.prototype.getInterimTile = function() { if (!this.interimTile) { @@ -148,7 +184,7 @@ Tile.prototype.refreshInterimChain = function() { /** * Get the tile coordinate for this tile. - * @return {ol.TileCoord} The tile coordinate. + * @return {module:ol/tilecoord~TileCoord} The tile coordinate. * @api */ Tile.prototype.getTileCoord = function() { @@ -157,14 +193,14 @@ Tile.prototype.getTileCoord = function() { /** - * @return {ol.TileState} State. + * @return {module:ol/TileState~TileState} State. */ Tile.prototype.getState = function() { return this.state; }; /** - * @param {ol.TileState} state State. + * @param {module:ol/TileState~TileState} state State. */ Tile.prototype.setState = function(state) { this.state = state; diff --git a/src/ol/TileCache.js b/src/ol/TileCache.js index 4c9ef844c4..d670733ed9 100644 --- a/src/ol/TileCache.js +++ b/src/ol/TileCache.js @@ -7,7 +7,7 @@ import {fromKey, getKey} from './tilecoord.js'; /** * @constructor - * @extends {ol.structs.LRUCache.} + * @extends {module:ol/structs/LRUCache~LRUCache.} * @param {number=} opt_highWaterMark High water mark. * @struct */ @@ -21,7 +21,7 @@ inherits(TileCache, LRUCache); /** - * @param {!Object.} usedTiles Used tiles. + * @param {!Object.} usedTiles Used tiles. */ TileCache.prototype.expireCache = function(usedTiles) { while (this.canExpireCache()) { diff --git a/src/ol/TileQueue.js b/src/ol/TileQueue.js index c5fe6a7eef..17ce82139d 100644 --- a/src/ol/TileQueue.js +++ b/src/ol/TileQueue.js @@ -7,10 +7,16 @@ import {listen, unlisten} from './events.js'; import EventType from './events/EventType.js'; import PriorityQueue from './structs/PriorityQueue.js'; + +/** + * @typedef {function(module:ol/Tile~Tile, string, module:ol/coordinate~Coordinate, number): number} PriorityFunction + */ + + /** * @constructor - * @extends {ol.structs.PriorityQueue.} - * @param {ol.TilePriorityFunction} tilePriorityFunction + * @extends {module:ol/structs/PriorityQueue~PriorityQueue.} + * @param {module:ol/TileQueue~PriorityFunction} tilePriorityFunction * Tile priority function. * @param {function(): ?} tileChangeCallback * Function called on each tile change event. @@ -32,7 +38,7 @@ const TileQueue = function(tilePriorityFunction, tileChangeCallback) { * @return {string} Key. */ function(element) { - return /** @type {ol.Tile} */ (element[0]).getKey(); + return /** @type {module:ol/Tile~Tile} */ (element[0]).getKey(); }); /** @@ -81,11 +87,11 @@ TileQueue.prototype.getTilesLoading = function() { /** - * @param {ol.events.Event} event Event. + * @param {module:ol/events/Event~Event} event Event. * @protected */ TileQueue.prototype.handleTileChange = function(event) { - const tile = /** @type {ol.Tile} */ (event.target); + const tile = /** @type {module:ol/Tile~Tile} */ (event.target); const state = tile.getState(); if (state === TileState.LOADED || state === TileState.ERROR || state === TileState.EMPTY || state === TileState.ABORT) { @@ -111,7 +117,7 @@ TileQueue.prototype.loadMoreTiles = function(maxTotalLoading, maxNewLoads) { let state, tile, tileKey; while (this.tilesLoading_ < maxTotalLoading && newLoads < maxNewLoads && this.getCount() > 0) { - tile = /** @type {ol.Tile} */ (this.dequeue()[0]); + tile = /** @type {module:ol/Tile~Tile} */ (this.dequeue()[0]); tileKey = tile.getKey(); state = tile.getState(); if (state === TileState.ABORT) { diff --git a/src/ol/TileRange.js b/src/ol/TileRange.js index 8aaabaf6f4..7e203238d1 100644 --- a/src/ol/TileRange.js +++ b/src/ol/TileRange.js @@ -42,8 +42,8 @@ const TileRange = function(minX, maxX, minY, maxY) { * @param {number} maxX Maximum X. * @param {number} minY Minimum Y. * @param {number} maxY Maximum Y. - * @param {ol.TileRange|undefined} tileRange TileRange. - * @return {ol.TileRange} Tile range. + * @param {module:ol/TileRange~TileRange=} tileRange TileRange. + * @return {module:ol/TileRange~TileRange} Tile range. */ export function createOrUpdate(minX, maxX, minY, maxY, tileRange) { if (tileRange !== undefined) { @@ -59,7 +59,7 @@ export function createOrUpdate(minX, maxX, minY, maxY, tileRange) { /** - * @param {ol.TileCoord} tileCoord Tile coordinate. + * @param {module:ol/tilecoord~TileCoord} tileCoord Tile coordinate. * @return {boolean} Contains tile coordinate. */ TileRange.prototype.contains = function(tileCoord) { @@ -68,7 +68,7 @@ TileRange.prototype.contains = function(tileCoord) { /** - * @param {ol.TileRange} tileRange Tile range. + * @param {module:ol/TileRange~TileRange} tileRange Tile range. * @return {boolean} Contains. */ TileRange.prototype.containsTileRange = function(tileRange) { @@ -88,7 +88,7 @@ TileRange.prototype.containsXY = function(x, y) { /** - * @param {ol.TileRange} tileRange Tile range. + * @param {module:ol/TileRange~TileRange} tileRange Tile range. * @return {boolean} Equals. */ TileRange.prototype.equals = function(tileRange) { @@ -98,7 +98,7 @@ TileRange.prototype.equals = function(tileRange) { /** - * @param {ol.TileRange} tileRange Tile range. + * @param {module:ol/TileRange~TileRange} tileRange Tile range. */ TileRange.prototype.extend = function(tileRange) { if (tileRange.minX < this.minX) { @@ -125,7 +125,7 @@ TileRange.prototype.getHeight = function() { /** - * @return {ol.Size} Size. + * @return {module:ol/size~Size} Size. */ TileRange.prototype.getSize = function() { return [this.getWidth(), this.getHeight()]; @@ -141,7 +141,7 @@ TileRange.prototype.getWidth = function() { /** - * @param {ol.TileRange} tileRange Tile range. + * @param {module:ol/TileRange~TileRange} tileRange Tile range. * @return {boolean} Intersects. */ TileRange.prototype.intersects = function(tileRange) { diff --git a/src/ol/VectorImageTile.js b/src/ol/VectorImageTile.js index 053beecdab..2fee0f23f2 100644 --- a/src/ol/VectorImageTile.js +++ b/src/ol/VectorImageTile.js @@ -10,27 +10,37 @@ import {getHeight, getIntersection, getWidth} from './extent.js'; import EventType from './events/EventType.js'; import {loadFeaturesXhr} from './featureloader.js'; + +/** + * @typedef {Object} ReplayState + * @property {boolean} dirty + * @property {null|module:ol/render~OrderFunction} renderedRenderOrder + * @property {number} renderedTileRevision + * @property {number} renderedRevision + */ + + /** * @constructor - * @extends {ol.Tile} - * @param {ol.TileCoord} tileCoord Tile coordinate. - * @param {ol.TileState} state State. + * @extends {module:ol/Tile~Tile} + * @param {module:ol/tilecoord~TileCoord} tileCoord Tile coordinate. + * @param {module:ol/TileState~TileState} state State. * @param {number} sourceRevision Source revision. - * @param {ol.format.Feature} format Feature format. - * @param {ol.TileLoadFunctionType} tileLoadFunction Tile load function. - * @param {ol.TileCoord} urlTileCoord Wrapped tile coordinate for source urls. - * @param {ol.TileUrlFunctionType} tileUrlFunction Tile url function. - * @param {ol.tilegrid.TileGrid} sourceTileGrid Tile grid of the source. - * @param {ol.tilegrid.TileGrid} tileGrid Tile grid of the renderer. - * @param {Object.} sourceTiles Source tiles. + * @param {module:ol/format/Feature~Feature} format Feature format. + * @param {module:ol/Tile~LoadFunction} tileLoadFunction Tile load function. + * @param {module:ol/tilecoord~TileCoord} urlTileCoord Wrapped tile coordinate for source urls. + * @param {module:ol/Tile~UrlFunction} tileUrlFunction Tile url function. + * @param {module:ol/tilegrid/TileGrid~TileGrid} sourceTileGrid Tile grid of the source. + * @param {module:ol/tilegrid/TileGrid~TileGrid} tileGrid Tile grid of the renderer. + * @param {Object.} sourceTiles Source tiles. * @param {number} pixelRatio Pixel ratio. - * @param {ol.proj.Projection} projection Projection. - * @param {function(new: ol.VectorTile, ol.TileCoord, ol.TileState, string, - * ol.format.Feature, ol.TileLoadFunctionType)} tileClass Class to + * @param {module:ol/proj/Projection~Projection} projection Projection. + * @param {function(new: module:ol/VectorTile~VectorTile, module:ol/tilecoord~TileCoord, module:ol/TileState~TileState, string, + * module:ol/format/Feature~Feature, module:ol/Tile~LoadFunction)} tileClass Class to * instantiate for source tiles. - * @param {function(this: ol.source.VectorTile, ol.events.Event)} handleTileChange + * @param {function(this: module:ol/source/VectorTile~VectorTile, module:ol/events/Event~Event)} handleTileChange * Function to call when a source tile's state changes. - * @param {olx.TileOptions=} opt_options Tile options. + * @param {module:ol/Tile~Options=} opt_options Tile options. */ const VectorImageTile = function(tileCoord, state, sourceRevision, format, tileLoadFunction, urlTileCoord, tileUrlFunction, sourceTileGrid, tileGrid, @@ -46,19 +56,19 @@ const VectorImageTile = function(tileCoord, state, sourceRevision, format, /** * @private - * @type {ol.FeatureLoader} + * @type {module:ol/featureloader~FeatureLoader} */ this.loader_; /** * @private - * @type {!Object.} + * @type {!Object.} */ this.replayState_ = {}; /** * @private - * @type {Object.} + * @type {Object.} */ this.sourceTiles_ = sourceTiles; @@ -74,17 +84,17 @@ const VectorImageTile = function(tileCoord, state, sourceRevision, format, this.sourceRevision_ = sourceRevision; /** - * @type {ol.TileCoord} + * @type {module:ol/tilecoord~TileCoord} */ this.wrappedTileCoord = urlTileCoord; /** - * @type {Array.} + * @type {Array.} */ this.loadListenerKeys_ = []; /** - * @type {Array.} + * @type {Array.} */ this.sourceTileListenerKeys_ = []; @@ -154,7 +164,7 @@ VectorImageTile.prototype.disposeInternal = function() { /** - * @param {ol.layer.Layer} layer Layer. + * @param {module:ol/layer/Layer~Layer} layer Layer. * @return {CanvasRenderingContext2D} The rendering context. */ VectorImageTile.prototype.getContext = function(layer) { @@ -168,7 +178,7 @@ VectorImageTile.prototype.getContext = function(layer) { /** * Get the Canvas for this tile. - * @param {ol.layer.Layer} layer Layer. + * @param {module:ol/layer/Layer~Layer} layer Layer. * @return {HTMLCanvasElement} Canvas. */ VectorImageTile.prototype.getImage = function(layer) { @@ -178,8 +188,8 @@ VectorImageTile.prototype.getImage = function(layer) { /** - * @param {ol.layer.Layer} layer Layer. - * @return {ol.TileReplayState} The replay state. + * @param {module:ol/layer/Layer~Layer} layer Layer. + * @return {module:ol/VectorImageTile~ReplayState} The replay state. */ VectorImageTile.prototype.getReplayState = function(layer) { const key = getUid(layer).toString(); @@ -205,7 +215,7 @@ VectorImageTile.prototype.getKey = function() { /** * @param {string} tileKey Key (tileCoord) of the source tile. - * @return {ol.VectorTile} Source tile. + * @return {module:ol/VectorTile~VectorTile} Source tile. */ VectorImageTile.prototype.getTile = function(tileKey) { return this.sourceTiles_[tileKey]; @@ -289,7 +299,7 @@ export default VectorImageTile; /** * Sets the loader for a tile. - * @param {ol.VectorTile} tile Vector tile. + * @param {module:ol/VectorTile~VectorTile} tile Vector tile. * @param {string} url URL. */ export function defaultLoadFunction(tile, url) { diff --git a/src/ol/VectorTile.js b/src/ol/VectorTile.js index d15204ba54..eda9642ad7 100644 --- a/src/ol/VectorTile.js +++ b/src/ol/VectorTile.js @@ -7,13 +7,13 @@ import TileState from './TileState.js'; /** * @constructor - * @extends {ol.Tile} - * @param {ol.TileCoord} tileCoord Tile coordinate. - * @param {ol.TileState} state State. + * @extends {module:ol/Tile~Tile} + * @param {module:ol/tilecoord~TileCoord} tileCoord Tile coordinate. + * @param {module:ol/TileState~TileState} state State. * @param {string} src Data source url. - * @param {ol.format.Feature} format Feature format. - * @param {ol.TileLoadFunctionType} tileLoadFunction Tile load function. - * @param {olx.TileOptions=} opt_options Tile options. + * @param {module:ol/format/Feature~Feature} format Feature format. + * @param {module:ol/Tile~LoadFunction} tileLoadFunction Tile load function. + * @param {module:ol/Tile~Options=} opt_options Tile options. */ const VectorTile = function(tileCoord, state, src, format, tileLoadFunction, opt_options) { @@ -26,44 +26,44 @@ const VectorTile = function(tileCoord, state, src, format, tileLoadFunction, opt /** * @private - * @type {ol.Extent} + * @type {module:ol/extent~Extent} */ this.extent_ = null; /** * @private - * @type {ol.format.Feature} + * @type {module:ol/format/Feature~Feature} */ this.format_ = format; /** * @private - * @type {Array.} + * @type {Array.} */ this.features_ = null; /** * @private - * @type {ol.FeatureLoader} + * @type {module:ol/featureloader~FeatureLoader} */ this.loader_; /** * Data projection * @private - * @type {ol.proj.Projection} + * @type {module:ol/proj/Projection~Projection} */ this.projection_; /** * @private - * @type {Object.} + * @type {Object.} */ this.replayGroups_ = {}; /** * @private - * @type {ol.TileLoadFunctionType} + * @type {module:ol/Tile~LoadFunction} */ this.tileLoadFunction_ = tileLoadFunction; @@ -79,7 +79,7 @@ inherits(VectorTile, Tile); /** * @const - * @type {ol.Extent} + * @type {module:ol/extent~Extent} */ const DEFAULT_EXTENT = [0, 0, 4096, 4096]; @@ -98,7 +98,7 @@ VectorTile.prototype.disposeInternal = function() { /** * Gets the extent of the vector tile. - * @return {ol.Extent} The extent. + * @return {module:ol/extent~Extent} The extent. * @api */ VectorTile.prototype.getExtent = function() { @@ -108,7 +108,7 @@ VectorTile.prototype.getExtent = function() { /** * Get the feature format assigned for reading this tile's features. - * @return {ol.format.Feature} Feature format. + * @return {module:ol/format/Feature~Feature} Feature format. * @api */ VectorTile.prototype.getFormat = function() { @@ -118,8 +118,8 @@ VectorTile.prototype.getFormat = function() { /** * Get the features for this tile. Geometries will be in the projection returned - * by {@link ol.VectorTile#getProjection}. - * @return {Array.} Features. + * by {@link module:ol/VectorTile~VectorTile#getProjection}. + * @return {Array.} Features. * @api */ VectorTile.prototype.getFeatures = function() { @@ -137,8 +137,8 @@ VectorTile.prototype.getKey = function() { /** * Get the feature projection of features returned by - * {@link ol.VectorTile#getFeatures}. - * @return {ol.proj.Projection} Feature projection. + * {@link module:ol/VectorTile~VectorTile#getFeatures}. + * @return {module:ol/proj/Projection~Projection} Feature projection. * @api */ VectorTile.prototype.getProjection = function() { @@ -147,9 +147,9 @@ VectorTile.prototype.getProjection = function() { /** - * @param {ol.layer.Layer} layer Layer. + * @param {module:ol/layer/Layer~Layer} layer Layer. * @param {string} key Key. - * @return {ol.render.ReplayGroup} Replay group. + * @return {module:ol/render/ReplayGroup~ReplayGroup} Replay group. */ VectorTile.prototype.getReplayGroup = function(layer, key) { return this.replayGroups_[getUid(layer) + ',' + key]; @@ -170,9 +170,9 @@ VectorTile.prototype.load = function() { /** * Handler for successful tile load. - * @param {Array.} features The loaded features. - * @param {ol.proj.Projection} dataProjection Data projection. - * @param {ol.Extent} extent Extent. + * @param {Array.} features The loaded features. + * @param {module:ol/proj/Projection~Projection} dataProjection Data projection. + * @param {module:ol/extent~Extent} extent Extent. */ VectorTile.prototype.onLoad = function(features, dataProjection, extent) { this.setProjection(dataProjection); @@ -190,15 +190,15 @@ VectorTile.prototype.onError = function() { /** - * Function for use in an {@link ol.source.VectorTile}'s `tileLoadFunction`. - * Sets the extent of the vector tile. This is only required for tiles in - * projections with `tile-pixels` as units. The extent should be set to - * `[0, 0, tilePixelSize, tilePixelSize]`, where `tilePixelSize` is calculated - * by multiplying the tile size with the tile pixel ratio. For sources using - * {@link ol.format.MVT} as feature format, the - * {@link ol.format.MVT#getLastExtent} method will return the correct extent. - * The default is `[0, 0, 4096, 4096]`. - * @param {ol.Extent} extent The extent. + * Function for use in an {@link module:ol/source/VectorTile~VectorTile}'s + * `tileLoadFunction`. Sets the extent of the vector tile. This is only required + * for tiles in projections with `tile-pixels` as units. The extent should be + * set to `[0, 0, tilePixelSize, tilePixelSize]`, where `tilePixelSize` is + * calculated by multiplying the tile size with the tile pixel ratio. For + * sources using {@link module:ol/format/MVT~MVT} as feature format, the + * {@link module:ol/format/MVT~MVT#getLastExtent} method will return the correct + * extent. The default is `[0, 0, 4096, 4096]`. + * @param {module:ol/extent~Extent} extent The extent. * @api */ VectorTile.prototype.setExtent = function(extent) { @@ -207,9 +207,9 @@ VectorTile.prototype.setExtent = function(extent) { /** - * Function for use in an {@link ol.source.VectorTile}'s `tileLoadFunction`. + * Function for use in an {@link module:ol/source/VectorTile~VectorTile}'s `tileLoadFunction`. * Sets the features for the tile. - * @param {Array.} features Features. + * @param {Array.} features Features. * @api */ VectorTile.prototype.setFeatures = function(features) { @@ -219,10 +219,10 @@ VectorTile.prototype.setFeatures = function(features) { /** - * Function for use in an {@link ol.source.VectorTile}'s `tileLoadFunction`. + * Function for use in an {@link module:ol/source/VectorTile~VectorTile}'s `tileLoadFunction`. * Sets the projection of the features that were added with - * {@link ol.VectorTile#setFeatures}. - * @param {ol.proj.Projection} projection Feature projection. + * {@link module:ol/VectorTile~VectorTile#setFeatures}. + * @param {module:ol/proj/Projection~Projection} projection Feature projection. * @api */ VectorTile.prototype.setProjection = function(projection) { @@ -231,9 +231,9 @@ VectorTile.prototype.setProjection = function(projection) { /** - * @param {ol.layer.Layer} layer Layer. + * @param {module:ol/layer/Layer~Layer} layer Layer. * @param {string} key Key. - * @param {ol.render.ReplayGroup} replayGroup Replay group. + * @param {module:ol/render/ReplayGroup~ReplayGroup} replayGroup Replay group. */ VectorTile.prototype.setReplayGroup = function(layer, key, replayGroup) { this.replayGroups_[getUid(layer) + ',' + key] = replayGroup; @@ -242,7 +242,7 @@ VectorTile.prototype.setReplayGroup = function(layer, key, replayGroup) { /** * Set the feature loader for reading this tile's features. - * @param {ol.FeatureLoader} loader Feature loader. + * @param {module:ol/featureloader~FeatureLoader} loader Feature loader. * @api */ VectorTile.prototype.setLoader = function(loader) { diff --git a/src/ol/View.js b/src/ol/View.js index 685fdffaf8..face844c5b 100644 --- a/src/ol/View.js +++ b/src/ol/View.js @@ -24,6 +24,116 @@ import {createProjection, METERS_PER_UNIT} from './proj.js'; import Units from './proj/Units.js'; +/** + * An animation configuration + * + * @typedef {Object} Animation + * @property {module:ol/coordinate~Coordinate} [sourceCenter] + * @property {module:ol/coordinate~Coordinate} [targetCenter] + * @property {number} [sourceResolution] + * @property {number} [targetResolution] + * @property {number} [sourceRotation] + * @property {number} [sourceRotation] + * @property {module:ol/coordinate~Coordinate} [anchor] + * @property {number} start + * @property {number} duration + * @property {boolean} complete + * @property {function(number):number} easing + * @property {function(boolean)} callback + */ + + +/** + * @typedef {Object} Constraints + * @property {module:ol/centerconstraint~Type} center + * @property {module:ol/resolutionconstraint~Type} resolution + * @property {module:ol/rotationconstraint~Type} rotation + */ + + +/** + * @typedef {Object} FitOptions + * @property {module:ol/size~Size} [size] The size in pixels of the box to fit + * the extent into. Default is the current size of the first map in the DOM that + * uses this view, or `[100, 100]` if no such map is found. + * @property {!Array.} [padding=[0, 0, 0, 0]] Padding (in pixels) to be + * cleared inside the view. Values in the array are top, right, bottom and left + * padding. + * @property {boolean} [constrainResolution=true] Constrain the resolution. + * @property {boolean} [nearest=false] If `constrainResolution` is `true`, get + * the nearest extent instead of the closest that actually fits the view. + * @property {number} [minResolution=0] Minimum resolution that we zoom to. + * @property {number} [maxZoom] Maximum zoom level that we zoom to. If + * `minResolution` is given, this property is ignored. + * @property {number} [duration] The duration of the animation in milliseconds. + * By default, there is no animation to the target extent. + * @property {function(number):number} [easing] The easing function used during + * the animation (defaults to {@link module:ol/easing~inAndOut}). + * The function will be called for each frame with a number representing a + * fraction of the animation's duration. The function should return a number + * between 0 and 1 representing the progress toward the destination state. + * @property {function(boolean)} [callback] Function called when the view is in + * its final position. The callback will be called with `true` if the animation + * series completed on its own or `false` if it was cancelled. + */ + + +/** + * @typedef {Object} ViewOptions + * @property {module:ol/coordinate~Coordinate~Coordinate} [center] The initial center for + * the view. The coordinate system for the center is specified with the + * `projection` option. Layer sources will not be fetched if this is not set, + * but the center can be set later with {@link #setCenter}. + * @property {boolean|number} [constrainRotation=true] Rotation constraint. + * `false` means no constraint. `true` means no constraint, but snap to zero + * near zero. A number constrains the rotation to that number of values. For + * example, `4` will constrain the rotation to 0, 90, 180, and 270 degrees. + * @property {boolean} [enableRotation=true] Enable rotation. + * If `false`, a rotation constraint that always sets the rotation to zero is + * used. The `constrainRotation` option has no effect if `enableRotation` is + * `false`. + * @property {module:ol/extent~Extent} [extent] The extent that constrains the + * center, in other words, center cannot be set outside this extent. + * @property {number} [maxResolution] The maximum resolution used to determine + * the resolution constraint. It is used together with `minResolution` (or + * `maxZoom`) and `zoomFactor`. If unspecified it is calculated in such a way + * that the projection's validity extent fits in a 256x256 px tile. If the + * projection is Spherical Mercator (the default) then `maxResolution` defaults + * to `40075016.68557849 / 256 = 156543.03392804097`. + * @property {number} [minResolution] The minimum resolution used to determine + * the resolution constraint. It is used together with `maxResolution` (or + * `minZoom`) and `zoomFactor`. If unspecified it is calculated assuming 29 + * zoom levels (with a factor of 2). If the projection is Spherical Mercator + * (the default) then `minResolution` defaults to + * `40075016.68557849 / 256 / Math.pow(2, 28) = 0.0005831682455839253`. + * @property {number} [maxZoom=28] The maximum zoom level used to determine the + * resolution constraint. It is used together with `minZoom` (or + * `maxResolution`) and `zoomFactor`. Note that if `minResolution` is also + * provided, it is given precedence over `maxZoom`. + * @property {number} [minZoom=0] The minimum zoom level used to determine the + * resolution constraint. It is used together with `maxZoom` (or + * `minResolution`) and `zoomFactor`. Note that if `maxResolution` is also + * provided, it is given precedence over `minZoom`. + * @property {module:ol/proj~ProjectionLike} [projection='EPSG:3857'] The + * projection. The default is Spherical Mercator. + * @property {number} [resolution] The initial resolution for the view. The + * units are `projection` units per pixel (e.g. meters per pixel). An + * alternative to setting this is to set `zoom`. Layer sources will not be + * fetched if neither this nor `zoom` are defined, but they can be set later + * with {@link #setZoom} or {@link #setResolution}. + * @property {Array.} [resolutions] Resolutions to determine the + * resolution constraint. If set the `maxResolution`, `minResolution`, + * `minZoom`, `maxZoom`, and `zoomFactor` options are ignored. + * @property {number} [rotation=0] The initial rotation for the view in radians + * (positive rotation clockwise, 0 means North). + * @property {number} [zoom] Only used if `resolution` is not defined. Zoom + * level used to calculate the initial resolution for the view. The initial + * resolution is determined using the {@link #constrainResolution} method. + * @property {number} [zoomFactor=2] The zoom factor used to determine the + * resolution constraint. + */ + + /** * Default min zoom level for the map view. * @type {number} @@ -33,18 +143,18 @@ const DEFAULT_MIN_ZOOM = 0; /** * @classdesc - * An ol.View object represents a simple 2D view of the map. + * A View object represents a simple 2D view of the map. * * This is the object to act upon to change the center, resolution, * and rotation of the map. * * ### The view states * - * An `ol.View` is determined by three states: `center`, `resolution`, + * An View is determined by three states: `center`, `resolution`, * and `rotation`. Each state has a corresponding getter and setter, e.g. * `getCenter` and `setCenter` for the `center` state. * - * An `ol.View` has a `projection`. The projection determines the + * An View has a `projection`. The projection determines the * coordinate system of the center, and its units determine the units of the * resolution (projection units per pixel). The default projection is * Spherical Mercator (EPSG:3857). @@ -56,7 +166,7 @@ const DEFAULT_MIN_ZOOM = 0; * that is passed to a setter will effectively be the value set in the view, * and returned by the corresponding getter. * - * But an `ol.View` object also has a *resolution constraint*, a + * But a View object also has a *resolution constraint*, a * *rotation constraint* and a *center constraint*. * * As said above, no constraints are applied when the setters are used to set @@ -84,8 +194,8 @@ const DEFAULT_MIN_ZOOM = 0; * default the center is not constrained at all. * * @constructor - * @extends {ol.Object} - * @param {olx.ViewOptions=} opt_options View options. + * @extends {module:ol/Object~Object} + * @param {module:ol/View~ViewOptions=} opt_options View options. * @api */ const View = function(opt_options) { @@ -101,7 +211,7 @@ const View = function(opt_options) { /** * @private - * @type {Array.>} + * @type {Array.>} */ this.animations_ = []; @@ -116,7 +226,7 @@ const View = function(opt_options) { /** * @private * @const - * @type {ol.proj.Projection} + * @type {module:ol/proj/Projection~Projection} */ this.projection_ = createProjection(options.projection, 'EPSG:3857'); @@ -128,7 +238,7 @@ inherits(View, BaseObject); /** * Set up the view with the given options. - * @param {olx.ViewOptions} options View options. + * @param {module:ol/View~ViewOptions} options View options. */ View.prototype.applyOptions_ = function(options) { @@ -178,7 +288,7 @@ View.prototype.applyOptions_ = function(options) { /** * @private - * @type {ol.Constraints} + * @type {module:ol/View~Constraints} */ this.constraints_ = { center: centerConstraint, @@ -203,7 +313,7 @@ View.prototype.applyOptions_ = function(options) { /** * @private - * @type {olx.ViewOptions} + * @type {module:ol/View~ViewOptions} */ this.options_ = options; @@ -214,8 +324,8 @@ View.prototype.applyOptions_ = function(options) { * current resolution (or zoom), center, and rotation are applied to any stored * options. The provided options can be uesd to apply new min/max zoom or * resolution limits. - * @param {olx.ViewOptions} newOptions New options to be applied. - * @return {olx.ViewOptions} New options updated with the current view state. + * @param {module:ol/View~ViewOptions} newOptions New options to be applied. + * @return {module:ol/View~ViewOptions} New options updated with the current view state. */ View.prototype.getUpdatedOptions_ = function(newOptions) { const options = assign({}, this.options_); @@ -246,7 +356,7 @@ View.prototype.getUpdatedOptions_ = function(newOptions) { * * By default, the animation lasts one second and uses in-and-out easing. You * can customize this behavior by including `duration` (in milliseconds) and - * `easing` options (see {@link ol.easing}). + * `easing` options (see {@link module:ol/easing}). * * To chain together multiple animations, call the method with multiple * animation objects. For example, to first zoom and then pan: @@ -304,7 +414,7 @@ View.prototype.animate = function(var_args) { for (let i = 0; i < animationCount; ++i) { const options = /** @type {olx.AnimationOptions} */ (arguments[i]); - const animation = /** @type {ol.ViewAnimation} */ ({ + const animation = /** @type {module:ol/View~Animation} */ ({ start: start, complete: false, anchor: options.anchor, @@ -472,8 +582,8 @@ View.prototype.updateAnimations_ = function() { /** * @param {number} rotation Target rotation. - * @param {ol.Coordinate} anchor Rotation anchor. - * @return {ol.Coordinate|undefined} Center for rotation and anchor. + * @param {module:ol/coordinate~Coordinate} anchor Rotation anchor. + * @return {module:ol/coordinate~Coordinate|undefined} Center for rotation and anchor. */ View.prototype.calculateCenterRotate = function(rotation, anchor) { let center; @@ -489,8 +599,8 @@ View.prototype.calculateCenterRotate = function(rotation, anchor) { /** * @param {number} resolution Target resolution. - * @param {ol.Coordinate} anchor Zoom anchor. - * @return {ol.Coordinate|undefined} Center for resolution and anchor. + * @param {module:ol/coordinate~Coordinate} anchor Zoom anchor. + * @return {module:ol/coordinate~Coordinate|undefined} Center for resolution and anchor. */ View.prototype.calculateCenterZoom = function(resolution, anchor) { let center; @@ -509,7 +619,7 @@ View.prototype.calculateCenterZoom = function(resolution, anchor) { /** * @private - * @return {ol.Size} Viewport size or `[100, 100]` when no viewport is found. + * @return {module:ol/size~Size} Viewport size or `[100, 100]` when no viewport is found. */ View.prototype.getSizeFromViewport_ = function() { const size = [100, 100]; @@ -526,8 +636,8 @@ View.prototype.getSizeFromViewport_ = function() { /** * Get the constrained center of this view. - * @param {ol.Coordinate|undefined} center Center. - * @return {ol.Coordinate|undefined} Constrained center. + * @param {module:ol/coordinate~Coordinate|undefined} center Center. + * @return {module:ol/coordinate~Coordinate|undefined} Constrained center. * @api */ View.prototype.constrainCenter = function(center) { @@ -565,17 +675,17 @@ View.prototype.constrainRotation = function(rotation, opt_delta) { /** * Get the view center. - * @return {ol.Coordinate|undefined} The center of the view. + * @return {module:ol/coordinate~Coordinate|undefined} The center of the view. * @observable * @api */ View.prototype.getCenter = function() { - return /** @type {ol.Coordinate|undefined} */ (this.get(ViewProperty.CENTER)); + return /** @type {module:ol/coordinate~Coordinate|undefined} */ (this.get(ViewProperty.CENTER)); }; /** - * @return {ol.Constraints} Constraints. + * @return {module:ol/View~Constraints} Constraints. */ View.prototype.getConstraints = function() { return this.constraints_; @@ -602,14 +712,14 @@ View.prototype.getHints = function(opt_hints) { * The size is the pixel dimensions of the box into which the calculated extent * should fit. In most cases you want to get the extent of the entire map, * that is `map.getSize()`. - * @param {ol.Size=} opt_size Box pixel size. If not provided, the size of the + * @param {module:ol/size~Size=} opt_size Box pixel size. If not provided, the size of the * first map that uses this view will be used. - * @return {ol.Extent} Extent. + * @return {module:ol/extent~Extent} Extent. * @api */ View.prototype.calculateExtent = function(opt_size) { const size = opt_size || this.getSizeFromViewport_(); - const center = /** @type {!ol.Coordinate} */ (this.getCenter()); + const center = /** @type {!module:ol/coordinate~Coordinate} */ (this.getCenter()); assert(center, 1); // The view center is not defined const resolution = /** @type {!number} */ (this.getResolution()); assert(resolution !== undefined, 2); // The view resolution is not defined @@ -682,7 +792,7 @@ View.prototype.setMinZoom = function(zoom) { /** * Get the view projection. - * @return {ol.proj.Projection} The projection of the view. + * @return {module:ol/proj/Projection~Projection} The projection of the view. * @api */ View.prototype.getProjection = function() { @@ -703,7 +813,7 @@ View.prototype.getResolution = function() { /** * Get the resolutions for the view. This returns the array of resolutions - * passed to the constructor of the {ol.View}, or undefined if none were given. + * passed to the constructor of the View, or undefined if none were given. * @return {Array.|undefined} The resolutions of the view. * @api */ @@ -714,8 +824,8 @@ View.prototype.getResolutions = function() { /** * Get the resolution for a provided extent (in map units) and size (in pixels). - * @param {ol.Extent} extent Extent. - * @param {ol.Size=} opt_size Box pixel size. + * @param {module:ol/extent~Extent} extent Extent. + * @param {module:ol/size~Size=} opt_size Box pixel size. * @return {number} The resolution at which the provided extent will render at * the given size. * @api @@ -790,7 +900,7 @@ View.prototype.getValueForResolutionFunction = function(opt_power) { * @return {olx.ViewState} View state. */ View.prototype.getState = function() { - const center = /** @type {ol.Coordinate} */ (this.getCenter()); + const center = /** @type {module:ol/coordinate~Coordinate} */ (this.getCenter()); const projection = this.getProjection(); const resolution = /** @type {number} */ (this.getResolution()); const rotation = this.getRotation(); @@ -864,7 +974,7 @@ View.prototype.getResolutionForZoom = function(zoom) { * The size is pixel dimensions of the box to fit the extent into. * In most cases you will want to use the map size, that is `map.getSize()`. * Takes care of the map angle. - * @param {ol.geom.SimpleGeometry|ol.Extent} geometryOrExtent The geometry or + * @param {module:ol/geom/SimpleGeometry~SimpleGeometry|module:ol/extent~Extent} geometryOrExtent The geometry or * extent to fit the view to. * @param {olx.view.FitOptions=} opt_options Options. * @api @@ -875,7 +985,7 @@ View.prototype.fit = function(geometryOrExtent, opt_options) { if (!size) { size = this.getSizeFromViewport_(); } - /** @type {ol.geom.SimpleGeometry} */ + /** @type {module:ol/geom/SimpleGeometry~SimpleGeometry} */ let geometry; if (!(geometryOrExtent instanceof SimpleGeometry)) { assert(Array.isArray(geometryOrExtent), @@ -967,9 +1077,9 @@ View.prototype.fit = function(geometryOrExtent, opt_options) { /** * Center on coordinate and view position. - * @param {ol.Coordinate} coordinate Coordinate. - * @param {ol.Size} size Box pixel size. - * @param {ol.Pixel} position Position on the view to center on. + * @param {module:ol/coordinate~Coordinate} coordinate Coordinate. + * @param {module:ol/size~Size} size Box pixel size. + * @param {module:ol~Pixel} position Position on the view to center on. * @api */ View.prototype.centerOn = function(coordinate, size, position) { @@ -1003,7 +1113,7 @@ View.prototype.isDef = function() { /** * Rotate the view around a given coordinate. * @param {number} rotation New rotation value for the view. - * @param {ol.Coordinate=} opt_anchor The rotation center. + * @param {module:ol/coordinate~Coordinate=} opt_anchor The rotation center. * @api */ View.prototype.rotate = function(rotation, opt_anchor) { @@ -1017,7 +1127,7 @@ View.prototype.rotate = function(rotation, opt_anchor) { /** * Set the center of the current view. - * @param {ol.Coordinate|undefined} center The center of the view. + * @param {module:ol/coordinate~Coordinate|undefined} center The center of the view. * @observable * @api */ @@ -1030,7 +1140,7 @@ View.prototype.setCenter = function(center) { /** - * @param {ol.ViewHint} hint Hint. + * @param {module:ol/ViewHint~ViewHint} hint Hint. * @param {number} delta Delta. * @return {number} New value. */ @@ -1080,8 +1190,8 @@ View.prototype.setZoom = function(zoom) { /** - * @param {olx.ViewOptions} options View options. - * @return {ol.CenterConstraintType} The constraint. + * @param {module:ol/View~ViewOptions} options View options. + * @return {module:ol/centerconstraint~Type} The constraint. */ export function createCenterConstraint(options) { if (options.extent !== undefined) { @@ -1093,8 +1203,8 @@ export function createCenterConstraint(options) { /** - * @param {olx.ViewOptions} options View options. - * @return {{constraint: ol.ResolutionConstraintType, maxResolution: number, + * @param {module:ol/View~ViewOptions} options View options. + * @return {{constraint: module:ol/resolutionconstraint~Type, maxResolution: number, * minResolution: number, zoomFactor: number}} The constraint. */ export function createResolutionConstraint(options) { @@ -1175,8 +1285,8 @@ export function createResolutionConstraint(options) { /** - * @param {olx.ViewOptions} options View options. - * @return {ol.RotationConstraintType} Rotation constraint. + * @param {module:ol/View~ViewOptions} options View options. + * @return {module:ol/rotationconstraint~Type} Rotation constraint. */ export function createRotationConstraint(options) { const enableRotation = options.enableRotation !== undefined ? @@ -1200,7 +1310,7 @@ export function createRotationConstraint(options) { /** * Determine if an animation involves no view change. - * @param {ol.ViewAnimation} animation The animation. + * @param {module:ol/View~Animation} animation The animation. * @return {boolean} The animation involves no view change. */ export function isNoopAnimation(animation) { diff --git a/src/ol/centerconstraint.js b/src/ol/centerconstraint.js index 3a800da38e..03a51e530d 100644 --- a/src/ol/centerconstraint.js +++ b/src/ol/centerconstraint.js @@ -5,14 +5,19 @@ import {clamp} from './math.js'; /** - * @param {ol.Extent} extent Extent. - * @return {ol.CenterConstraintType} The constraint. + * @typedef {function((module:ol/coordinate~Coordinate|undefined)): (module:ol/coordinate~Coordinate|undefined)} Type + */ + + +/** + * @param {module:ol/extent~Extent} extent Extent. + * @return {module:ol/centerconstraint~Type} The constraint. */ export function createExtent(extent) { return ( /** - * @param {ol.Coordinate|undefined} center Center. - * @return {ol.Coordinate|undefined} Center. + * @param {module:ol/coordinate~Coordinate=} center Center. + * @return {module:ol/coordinate~Coordinate|undefined} Center. */ function(center) { if (center) { @@ -29,8 +34,8 @@ export function createExtent(extent) { /** - * @param {ol.Coordinate|undefined} center Center. - * @return {ol.Coordinate|undefined} Center. + * @param {module:ol/coordinate~Coordinate=} center Center. + * @return {module:ol/coordinate~Coordinate|undefined} Center. */ export function none(center) { return center; diff --git a/src/ol/color.js b/src/ol/color.js index 900eba70dd..e96b5a99a4 100644 --- a/src/ol/color.js +++ b/src/ol/color.js @@ -5,6 +5,16 @@ import {assert} from './asserts.js'; import {clamp} from './math.js'; +/** + * A color represented as a short array [red, green, blue, alpha]. + * red, green, and blue should be integers in the range 0..255 inclusive. + * alpha should be a float in the range 0..1 inclusive. If no alpha value is + * given then `1` will be used. + * @typedef {Array.} Color + * @api + */ + + /** * This RegExp matches # followed by 3, 4, 6, or 8 hex digits. * @const @@ -25,7 +35,7 @@ const NAMED_COLOR_RE_ = /^([a-z]*)$/i; /** * Return the color as an rgba string. - * @param {ol.Color|string} color Color. + * @param {module:ol/color~Color|string} color Color. * @return {string} Rgba string. * @api */ @@ -58,7 +68,7 @@ function fromNamed(color) { /** * @param {string} s String. - * @return {ol.Color} Color. + * @return {module:ol/color~Color} Color. */ export const fromString = ( function() { @@ -74,7 +84,7 @@ export const fromString = ( const MAX_CACHE_SIZE = 1024; /** - * @type {Object.} + * @type {Object.} */ const cache = {}; @@ -86,7 +96,7 @@ export const fromString = ( return ( /** * @param {string} s String. - * @return {ol.Color} Color. + * @return {module:ol/color~Color} Color. */ function(s) { let color; @@ -115,8 +125,8 @@ export const fromString = ( /** * Return the color as an array. This function maintains a cache of calculated * arrays which means the result should not be modified. - * @param {ol.Color|string} color Color. - * @return {ol.Color} Color. + * @param {module:ol/color~Color|string} color Color. + * @return {module:ol/color~Color} Color. * @api */ export function asArray(color) { @@ -130,7 +140,7 @@ export function asArray(color) { /** * @param {string} s String. * @private - * @return {ol.Color} Color. + * @return {module:ol/color~Color} Color. */ function fromStringInternal_(s) { let r, g, b, a, color; @@ -175,14 +185,14 @@ function fromStringInternal_(s) { } else { assert(false, 14); // Invalid color } - return /** @type {ol.Color} */ (color); + return /** @type {module:ol/color~Color} */ (color); } /** * TODO this function is only used in the test, we probably shouldn't export it - * @param {ol.Color} color Color. - * @return {ol.Color} Clamped color. + * @param {module:ol/color~Color} color Color. + * @return {module:ol/color~Color} Clamped color. */ export function normalize(color) { color[0] = clamp((color[0] + 0.5) | 0, 0, 255); @@ -194,7 +204,7 @@ export function normalize(color) { /** - * @param {ol.Color} color Color. + * @param {module:ol/color~Color} color Color. * @return {string} String. */ export function toString(color) { diff --git a/src/ol/color.jsdoc b/src/ol/color.jsdoc deleted file mode 100644 index 569033933c..0000000000 --- a/src/ol/color.jsdoc +++ /dev/null @@ -1,8 +0,0 @@ -/** - * Colors can be defined as a {@link ol.Color} array, or as strings in - * `rgb(r,g,b)` or `rgba(r,g,b,a)` format, or in hex `#rrggbb` or `#rgb` format. - * Color names, like 'red', 'blue' or 'green', may also be used with the - * Canvas renderer. - * - * @namespace ol.color - */ diff --git a/src/ol/colorlike.js b/src/ol/colorlike.js index ede1fd0b17..80c23e67fa 100644 --- a/src/ol/colorlike.js +++ b/src/ol/colorlike.js @@ -5,22 +5,34 @@ import {toString} from './color.js'; /** - * @param {ol.Color|ol.ColorLike} color Color. - * @return {ol.ColorLike} The color as an ol.ColorLike + * A type accepted by CanvasRenderingContext2D.fillStyle + * or CanvasRenderingContext2D.strokeStyle. + * Represents a color, pattern, or gradient. The origin for patterns and + * gradients as fill style is the top-left corner of the extent of the geometry + * being filled. + * + * @typedef {string|CanvasPattern|CanvasGradient} ColorLike + * @api + */ + + +/** + * @param {module:ol/color~Color|module:ol/colorlike~ColorLike} color Color. + * @return {module:ol/color~ColorLike} The color as an {@link ol/color~ColorLike}. * @api */ export function asColorLike(color) { if (isColorLike(color)) { return /** @type {string|CanvasPattern|CanvasGradient} */ (color); } else { - return toString(/** @type {ol.Color} */ (color)); + return toString(/** @type {module:ol/color~Color} */ (color)); } } /** - * @param {?} color The value that is potentially an ol.ColorLike - * @return {boolean} Whether the color is an ol.ColorLike + * @param {?} color The value that is potentially an {@link ol/color~ColorLike}. + * @return {boolean} The color is an {@link ol/color~ColorLike}. */ export function isColorLike(color) { return ( diff --git a/src/ol/colorlike.jsdoc b/src/ol/colorlike.jsdoc deleted file mode 100644 index c6e0c31397..0000000000 --- a/src/ol/colorlike.jsdoc +++ /dev/null @@ -1,5 +0,0 @@ -/** - * An {@link ol.ColorLike} can be a color, gradient or pattern accepted by - * [CanvasRenderingContext2D.fillStyle](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/fillStyle). - * @namespace ol.colorlike - */ diff --git a/src/ol/control.js b/src/ol/control.js index cc7d3eadf0..9db378f6e5 100644 --- a/src/ol/control.js +++ b/src/ol/control.js @@ -7,16 +7,35 @@ import Rotate from './control/Rotate.js'; import Zoom from './control/Zoom.js'; +/** + * @typedef {Object} DefaultsOptions + * @property {boolean|undefined} [attribution=true] Include + * {@link module:ol/control/Attribution~Attribution}. + * @property {module:ol/control/Attribution~AttributionOptions} [attributionOptions] + * Options for {@link module:ol/control/Attribution~Attribution}. + * @property {boolean} [rotate=true] Include + * {@link module:ol/control/Rotate~Rotate}. + * @property {module:ol/control/Rotate~RotateOptions} [rotateOptions] Options + * for {@link module:ol/control/Rotate~Rotate}. + * @property {boolean} [zoom] Include {@link module:ol/control/Zoom~Zoom}. + * @property {module:ol/control/Zoom~ZoomOptions} [zoomOptions] Options for + * {@link module:ol/control/Zoom~Zoom}. + * @api + */ + + /** * Set of controls included in maps by default. Unless configured otherwise, * this returns a collection containing an instance of each of the following * controls: - * * {@link ol.control.Zoom} - * * {@link ol.control.Rotate} - * * {@link ol.control.Attribution} + * * {@link module:ol/control/Zoom~Zoom} + * * {@link module:ol/control/Rotate~Rotate} + * * {@link module:ol/control/Attribution~Attribution} * - * @param {olx.control.DefaultsOptions=} opt_options Defaults options. - * @return {ol.Collection.} Controls. + * @param {module:ol/control~DefaultsOptions~DefaultsOptions=} opt_options + * Defaults options. + * @return {module:ol/Collection~Collection.} + * Controls. * @api */ export function defaults(opt_options) { diff --git a/src/ol/control/Control.js b/src/ol/control/Control.js index adfaa865ec..92e35f208e 100644 --- a/src/ol/control/Control.js +++ b/src/ol/control/Control.js @@ -61,7 +61,7 @@ const Control = function(options) { /** * @protected - * @type {!Array.} + * @type {!Array.} */ this.listenerKeys = []; diff --git a/src/ol/control/MousePosition.js b/src/ol/control/MousePosition.js index 65e62beca1..0909395070 100644 --- a/src/ol/control/MousePosition.js +++ b/src/ol/control/MousePosition.js @@ -78,13 +78,13 @@ const MousePosition = function(opt_options) { /** * @private - * @type {?ol.TransformFunction} + * @type {?module:ol/proj~TransformFunction} */ this.transform_ = null; /** * @private - * @type {ol.Pixel} + * @type {module:ol~Pixel} */ this.lastMouseMovePixel_ = null; @@ -124,13 +124,13 @@ MousePosition.prototype.handleProjectionChanged_ = function() { /** * Return the coordinate format type used to render the current position or * undefined. - * @return {ol.CoordinateFormatType|undefined} The format to render the current + * @return {module:ol/coordinate~CoordinateFormat|undefined} The format to render the current * position in. * @observable * @api */ MousePosition.prototype.getCoordinateFormat = function() { - return /** @type {ol.CoordinateFormatType|undefined} */ (this.get(COORDINATE_FORMAT)); + return /** @type {module:ol/coordinate~CoordinateFormat|undefined} */ (this.get(COORDINATE_FORMAT)); }; @@ -187,7 +187,7 @@ MousePosition.prototype.setMap = function(map) { /** * Set the coordinate format type used to render the current position. - * @param {ol.CoordinateFormatType} format The format to render the current + * @param {module:ol/coordinate~CoordinateFormat} format The format to render the current * position in. * @observable * @api @@ -199,7 +199,7 @@ MousePosition.prototype.setCoordinateFormat = function(format) { /** * Set the projection that is used to report the mouse position. - * @param {ol.ProjectionLike} projection The projection to report mouse + * @param {module:ol/proj~ProjectionLike} projection The projection to report mouse * position in. * @observable * @api @@ -210,7 +210,7 @@ MousePosition.prototype.setProjection = function(projection) { /** - * @param {?ol.Pixel} pixel Pixel. + * @param {?module:ol~Pixel} pixel Pixel. * @private */ MousePosition.prototype.updateHTML_ = function(pixel) { diff --git a/src/ol/control/OverviewMap.js b/src/ol/control/OverviewMap.js index d0ac6ebaaa..80f870fc0e 100644 --- a/src/ol/control/OverviewMap.js +++ b/src/ol/control/OverviewMap.js @@ -329,12 +329,12 @@ OverviewMap.prototype.validateExtent_ = function() { return; } - const mapSize = /** @type {ol.Size} */ (map.getSize()); + const mapSize = /** @type {module:ol/size~Size} */ (map.getSize()); const view = map.getView(); const extent = view.calculateExtent(mapSize); - const ovmapSize = /** @type {ol.Size} */ (ovmap.getSize()); + const ovmapSize = /** @type {module:ol/size~Size} */ (ovmap.getSize()); const ovview = ovmap.getView(); const ovextent = ovview.calculateExtent(ovmapSize); @@ -374,7 +374,7 @@ OverviewMap.prototype.resetExtent_ = function() { const map = this.getMap(); const ovmap = this.ovmap_; - const mapSize = /** @type {ol.Size} */ (map.getSize()); + const mapSize = /** @type {module:ol/size~Size} */ (map.getSize()); const view = map.getView(); const extent = view.calculateExtent(mapSize); @@ -421,7 +421,7 @@ OverviewMap.prototype.updateBox_ = function() { return; } - const mapSize = /** @type {ol.Size} */ (map.getSize()); + const mapSize = /** @type {module:ol/size~Size} */ (map.getSize()); const view = map.getView(); @@ -450,8 +450,8 @@ OverviewMap.prototype.updateBox_ = function() { /** * @param {number} rotation Target rotation. - * @param {ol.Coordinate} coordinate Coordinate. - * @return {ol.Coordinate|undefined} Coordinate for rotation and center anchor. + * @param {module:ol/coordinate~Coordinate} coordinate Coordinate. + * @return {module:ol/coordinate~Coordinate|undefined} Coordinate for rotation and center anchor. * @private */ OverviewMap.prototype.calculateCoordinateRotate_ = function( diff --git a/src/ol/control/ZoomSlider.js b/src/ol/control/ZoomSlider.js index b5b2ff460e..2685b7abf1 100644 --- a/src/ol/control/ZoomSlider.js +++ b/src/ol/control/ZoomSlider.js @@ -92,7 +92,7 @@ const ZoomSlider = function(opt_options) { /** * The calculated thumb size (border box plus margins). Set when initSlider_ * is called. - * @type {ol.Size} + * @type {module:ol/size~Size} * @private */ this.thumbSize_ = null; diff --git a/src/ol/control/ZoomToExtent.js b/src/ol/control/ZoomToExtent.js index 23eee1703a..022021c202 100644 --- a/src/ol/control/ZoomToExtent.js +++ b/src/ol/control/ZoomToExtent.js @@ -21,7 +21,7 @@ const ZoomToExtent = function(opt_options) { const options = opt_options ? opt_options : {}; /** - * @type {ol.Extent} + * @type {module:ol/extent~Extent} * @protected */ this.extent = options.extent ? options.extent : null; diff --git a/src/ol/coordinate.js b/src/ol/coordinate.js index d4bde5cfcb..7d55aed45e 100644 --- a/src/ol/coordinate.js +++ b/src/ol/coordinate.js @@ -5,19 +5,38 @@ import {modulo} from './math.js'; import {padNumber} from './string.js'; +/** + * An array of numbers representing an xy coordinate. Example: `[16, 48]`. + * @typedef {Array.} Coordinate + * @api + */ + + +/** + * A function that takes a {@link module:ol/coordinate~Coordinate} and + * transforms it into a `{string}`. + * + * @typedef {function((module:ol/coordinate~CoordinateFormat|undefined)): string} CoordinateFormat + * @api + */ + + /** * Add `delta` to `coordinate`. `coordinate` is modified in place and returned * by the function. * * Example: * + * import {add} from 'ol/coordinate'; + * * var coord = [7.85, 47.983333]; - * ol.coordinate.add(coord, [-2, 4]); + * add(coord, [-2, 4]); * // coord is now [5.85, 51.983333] * - * @param {ol.Coordinate} coordinate Coordinate. - * @param {ol.Coordinate} delta Delta. - * @return {ol.Coordinate} The input coordinate adjusted by the given delta. + * @param {module:ol/coordinate~Coordinate} coordinate Coordinate. + * @param {module:ol/coordinate~Coordinate} delta Delta. + * @return {module:ol/coordinate~Coordinate} The input coordinate adjusted by + * the given delta. * @api */ export function add(coordinate, delta) { @@ -30,9 +49,9 @@ export function add(coordinate, delta) { /** * Calculates the point closest to the passed coordinate on the passed circle. * - * @param {ol.Coordinate} coordinate The coordinate. - * @param {ol.geom.Circle} circle The circle. - * @return {ol.Coordinate} Closest point on the circumference + * @param {module:ol/coordinate~Coordinate} coordinate The coordinate. + * @param {module:ol/geom/Circle~Circle} circle The circle. + * @return {module:ol/coordinate~Coordinate} Closest point on the circumference. */ export function closestOnCircle(coordinate, circle) { const r = circle.getRadius(); @@ -62,10 +81,11 @@ export function closestOnCircle(coordinate, circle) { * the foot is on the segment, or the closest segment coordinate when the foot * is outside the segment. * - * @param {ol.Coordinate} coordinate The coordinate. - * @param {Array.} segment The two coordinates of the segment. - * @return {ol.Coordinate} The foot of the perpendicular of the coordinate to - * the segment. + * @param {module:ol/coordinate~Coordinate} coordinate The coordinate. + * @param {Array.} segment The two coordinates + * of the segment. + * @return {module:ol/coordinate~Coordinate} The foot of the perpendicular of + * the coordinate to the segment. */ export function closestOnSegment(coordinate, segment) { const x0 = coordinate[0]; @@ -96,32 +116,37 @@ export function closestOnSegment(coordinate, segment) { /** - * Returns a {@link ol.CoordinateFormatType} function that can be used to format - * a {ol.Coordinate} to a string. + * Returns a {@link module:ol/coordinate~CoordinateFormat} function that can be + * used to format + * a {module:ol/coordinate~Coordinate} to a string. * * Example without specifying the fractional digits: * + * import {createStringXY} from 'ol/coordinate'; + * * var coord = [7.85, 47.983333]; - * var stringifyFunc = ol.coordinate.createStringXY(); + * var stringifyFunc = createStringXY(); * var out = stringifyFunc(coord); * // out is now '8, 48' * * Example with explicitly specifying 2 fractional digits: * + * import {createStringXY} from 'ol/coordinate'; + * * var coord = [7.85, 47.983333]; - * var stringifyFunc = ol.coordinate.createStringXY(2); + * var stringifyFunc = createStringXY(2); * var out = stringifyFunc(coord); * // out is now '7.85, 47.98' * * @param {number=} opt_fractionDigits The number of digits to include * after the decimal point. Default is `0`. - * @return {ol.CoordinateFormatType} Coordinate format. + * @return {module:ol/coordinate~CoordinateFormat} Coordinate format. * @api */ export function createStringXY(opt_fractionDigits) { return ( /** - * @param {ol.Coordinate|undefined} coordinate Coordinate. + * @param {module:ol/coordinate~Coordinate} coordinate Coordinate. * @return {string} String XY. */ function(coordinate) { @@ -166,25 +191,29 @@ export function degreesToStringHDMS(hemispheres, degrees, opt_fractionDigits) { /** - * Transforms the given {@link ol.Coordinate} to a string using the given string - * template. The strings `{x}` and `{y}` in the template will be replaced with - * the first and second coordinate values respectively. + * Transforms the given {@link module:ol/coordinate~Coordinate} to a string + * using the given string template. The strings `{x}` and `{y}` in the template + * will be replaced with the first and second coordinate values respectively. * * Example without specifying the fractional digits: * + * import {format} from 'ol/coordinate'; + * * var coord = [7.85, 47.983333]; * var template = 'Coordinate is ({x}|{y}).'; - * var out = ol.coordinate.format(coord, template); + * var out = format(coord, template); * // out is now 'Coordinate is (8|48).' * * Example explicitly specifying the fractional digits: * + * import {format} from 'ol/coordinate'; + * * var coord = [7.85, 47.983333]; * var template = 'Coordinate is ({x}|{y}).'; - * var out = ol.coordinate.format(coord, template, 2); + * var out = format(coord, template, 2); * // out is now 'Coordinate is (7.85|47.98).' * - * @param {ol.Coordinate|undefined} coordinate Coordinate. + * @param {module:ol/coordinate~Coordinate} coordinate Coordinate. * @param {string} template A template string with `{x}` and `{y}` placeholders * that will be replaced by first and second coordinate values. * @param {number=} opt_fractionDigits The number of digits to include @@ -204,8 +233,8 @@ export function format(coordinate, template, opt_fractionDigits) { /** - * @param {ol.Coordinate} coordinate1 First coordinate. - * @param {ol.Coordinate} coordinate2 Second coordinate. + * @param {module:ol/coordinate~Coordinate} coordinate1 First coordinate. + * @param {module:ol/coordinate~Coordinate} coordinate2 Second coordinate. * @return {boolean} The two coordinates are equal. */ export function equals(coordinate1, coordinate2) { @@ -226,14 +255,16 @@ export function equals(coordinate1, coordinate2) { * * Example: * + * import {rotate} from 'ol/coordinate'; + * * var coord = [7.85, 47.983333]; * var rotateRadians = Math.PI / 2; // 90 degrees - * ol.coordinate.rotate(coord, rotateRadians); + * rotate(coord, rotateRadians); * // coord is now [-47.983333, 7.85] * - * @param {ol.Coordinate} coordinate Coordinate. + * @param {module:ol/coordinate~Coordinate} coordinate Coordinate. * @param {number} angle Angle in radian. - * @return {ol.Coordinate} Coordinate. + * @return {module:ol/coordinate~Coordinate} Coordinate. * @api */ export function rotate(coordinate, angle) { @@ -253,14 +284,16 @@ export function rotate(coordinate, angle) { * * Example: * + * import {scale as scaleCoordinate} from 'ol/coordinate'; + * * var coord = [7.85, 47.983333]; * var scale = 1.2; - * ol.coordinate.scale(coord, scale); + * scaleCoordinate(coord, scale); * // coord is now [9.42, 57.5799996] * - * @param {ol.Coordinate} coordinate Coordinate. + * @param {module:ol/coordinate~Coordinate} coordinate Coordinate. * @param {number} scale Scale factor. - * @return {ol.Coordinate} Coordinate. + * @return {module:ol/coordinate~Coordinate} Coordinate. */ export function scale(coordinate, scale) { coordinate[0] *= scale; @@ -270,8 +303,8 @@ export function scale(coordinate, scale) { /** - * @param {ol.Coordinate} coord1 First coordinate. - * @param {ol.Coordinate} coord2 Second coordinate. + * @param {module:ol/coordinate~Coordinate} coord1 First coordinate. + * @param {module:ol/coordinate~Coordinate} coord2 Second coordinate. * @return {number} Squared distance between coord1 and coord2. */ export function squaredDistance(coord1, coord2) { @@ -282,8 +315,8 @@ export function squaredDistance(coord1, coord2) { /** - * @param {ol.Coordinate} coord1 First coordinate. - * @param {ol.Coordinate} coord2 Second coordinate. + * @param {module:ol/coordinate~Coordinate} coord1 First coordinate. + * @param {module:ol/coordinate~Coordinate} coord2 Second coordinate. * @return {number} Distance between coord1 and coord2. */ export function distance(coord1, coord2) { @@ -294,8 +327,9 @@ export function distance(coord1, coord2) { /** * Calculate the squared distance from a coordinate to a line segment. * - * @param {ol.Coordinate} coordinate Coordinate of the point. - * @param {Array.} segment Line segment (2 coordinates). + * @param {module:ol/coordinate~Coordinate} coordinate Coordinate of the point. + * @param {Array.} segment Line segment (2 + * coordinates). * @return {number} Squared distance from the point to the line segment. */ export function squaredDistanceToSegment(coordinate, segment) { @@ -310,17 +344,21 @@ export function squaredDistanceToSegment(coordinate, segment) { * * Example without specifying fractional digits: * + * import {toStringHDMS} from 'ol/coordinate'; + * * var coord = [7.85, 47.983333]; - * var out = ol.coordinate.toStringHDMS(coord); + * var out = toStringHDMS(coord); * // out is now '47° 58′ 60″ N 7° 50′ 60″ E' * * Example explicitly specifying 1 fractional digit: * + * import {toStringHDMS} from 'ol/coordinate'; + * * var coord = [7.85, 47.983333]; - * var out = ol.coordinate.toStringHDMS(coord, 1); + * var out = toStringHDMS(coord, 1); * // out is now '47° 58′ 60.0″ N 7° 50′ 60.0″ E' * - * @param {ol.Coordinate|undefined} coordinate Coordinate. + * @param {module:ol/coordinate~Coordinate} coordinate Coordinate. * @param {number=} opt_fractionDigits The number of digits to include * after the decimal point. Default is `0`. * @return {string} Hemisphere, degrees, minutes and seconds. @@ -341,17 +379,21 @@ export function toStringHDMS(coordinate, opt_fractionDigits) { * * Example without specifying fractional digits: * + * import {toStringXY} from 'ol/coordinate'; + * * var coord = [7.85, 47.983333]; - * var out = ol.coordinate.toStringXY(coord); + * var out = toStringXY(coord); * // out is now '8, 48' * * Example explicitly specifying 1 fractional digit: * + * import {toStringXY} from 'ol/coordinate'; + * * var coord = [7.85, 47.983333]; - * var out = ol.coordinate.toStringXY(coord, 1); + * var out = toStringXY(coord, 1); * // out is now '7.8, 48.0' * - * @param {ol.Coordinate|undefined} coordinate Coordinate. + * @param {module:ol/coordinate~Coordinate} coordinate Coordinate. * @param {number=} opt_fractionDigits The number of digits to include * after the decimal point. Default is `0`. * @return {string} XY. diff --git a/src/ol/coordinate.jsdoc b/src/ol/coordinate.jsdoc deleted file mode 100644 index 282f35ac87..0000000000 --- a/src/ol/coordinate.jsdoc +++ /dev/null @@ -1,3 +0,0 @@ -/** - * @namespace ol.coordinate - */ diff --git a/src/ol/easing.js b/src/ol/easing.js index aebd94a886..7a64d450e9 100644 --- a/src/ol/easing.js +++ b/src/ol/easing.js @@ -49,8 +49,8 @@ export function linear(t) { /** * Start slow, speed up, and at the very end slow down again. This has the - * same general behavior as {@link ol.easing.inAndOut}, but the final slowdown - * is delayed. + * same general behavior as {@link module:ol/easing~inAndOut}, but the final + * slowdown is delayed. * @param {number} t Input between 0 and 1. * @return {number} Output between 0 and 1. * @api diff --git a/src/ol/easing.jsdoc b/src/ol/easing.jsdoc deleted file mode 100644 index 1a3dad223e..0000000000 --- a/src/ol/easing.jsdoc +++ /dev/null @@ -1,4 +0,0 @@ -/** - * Easing functions for {@link ol.View#animate}. - * @namespace ol.easing - */ diff --git a/src/ol/events.js b/src/ol/events.js index 7763e1c3d4..720c0386d1 100644 --- a/src/ol/events.js +++ b/src/ol/events.js @@ -5,8 +5,31 @@ import {clear} from './obj.js'; /** - * @param {ol.EventsKey} listenerObj Listener object. - * @return {ol.EventsListenerFunctionType} Bound listener. + * Key to use with {@link module:ol/Observable~Observable#unByKey}. + * @typedef {Object} EventsKey + * @property {Object} [bindTo] + * @property {module:ol/events~ListenerFunction} [boundListener] + * @property {boolean} callOnce + * @property {number} [deleteIndex] + * @property {module:ol/events~ListenerFunction} listener + * @property {EventTarget|module:ol/events/EventTarget~EventTarget} target + * @property {string} type + * @api + */ + + +/** + * Listener function. This function is called with an event object as argument. + * When the function returns `false`, event propagation will stop. + * + * @typedef {function(module:ol/events/Event~Event)|function(module:ol/events/Event~Event): boolean} ListenerFunction + * @api + */ + + +/** + * @param {module:ol/events~EventsKey} listenerObj Listener object. + * @return {module:ol/events~ListenerFunction} Bound listener. */ export function bindListener(listenerObj) { const boundListener = function(evt) { @@ -23,15 +46,15 @@ export function bindListener(listenerObj) { /** - * Finds the matching {@link ol.EventsKey} in the given listener + * Finds the matching {@link module:ol/events~EventsKey} in the given listener * array. * - * @param {!Array} listeners Array of listeners. + * @param {!Array} listeners Array of listeners. * @param {!Function} listener The listener function. * @param {Object=} opt_this The `this` value inside the listener. * @param {boolean=} opt_setDeleteIndex Set the deleteIndex on the matching - * listener, for {@link ol.events.unlistenByKey}. - * @return {ol.EventsKey|undefined} The matching listener object. + * listener, for {@link module:ol/events~unlistenByKey}. + * @return {module:ol/events~EventsKey|undefined} The matching listener object. */ export function findListener(listeners, listener, opt_this, opt_setDeleteIndex) { let listenerObj; @@ -50,9 +73,9 @@ export function findListener(listeners, listener, opt_this, opt_setDeleteIndex) /** - * @param {ol.EventTargetLike} target Target. + * @param {module:ol/events/EventTarget~EventTargetLike} target Target. * @param {string} type Type. - * @return {Array.|undefined} Listeners. + * @return {Array.|undefined} Listeners. */ export function getListeners(target, type) { const listenerMap = target.ol_lm; @@ -63,8 +86,8 @@ export function getListeners(target, type) { /** * Get the lookup of listeners. If one does not exist on the target, it is * created. - * @param {ol.EventTargetLike} target Target. - * @return {!Object.>} Map of + * @param {module:ol/events/EventTarget~EventTargetLike} target Target. + * @return {!Object.>} Map of * listeners by event type. */ function getListenerMap(target) { @@ -80,7 +103,7 @@ function getListenerMap(target) { * Clean up all listener objects of the given type. All properties on the * listener objects will be removed, and if no listeners remain in the listener * map, it will be removed from the target. - * @param {ol.EventTargetLike} target Target. + * @param {module:ol/events/EventTarget~EventTargetLike} target Target. * @param {string} type Type. */ function removeListeners(target, type) { @@ -107,15 +130,15 @@ function removeListeners(target, type) { * {@link https://google.github.io/closure-library/api/source/closure/goog/events/events.js.src.html} * * This function efficiently binds a `listener` to a `this` object, and returns - * a key for use with {@link ol.events.unlistenByKey}. + * a key for use with {@link module:ol/events~unlistenByKey}. * - * @param {ol.EventTargetLike} target Event target. + * @param {module:ol/events/EventTarget~EventTargetLike} target Event target. * @param {string} type Event type. - * @param {ol.EventsListenerFunctionType} listener Listener. + * @param {module:ol/events~ListenerFunction} listener Listener. * @param {Object=} opt_this Object referenced by the `this` keyword in the * listener. Default is the `target`. * @param {boolean=} opt_once If true, add the listener as one-off listener. - * @return {ol.EventsKey} Unique key for the listener. + * @return {module:ol/events~EventsKey} Unique key for the listener. */ export function listen(target, type, listener, opt_this, opt_once) { const listenerMap = getListenerMap(target); @@ -130,7 +153,7 @@ export function listen(target, type, listener, opt_this, opt_once) { listenerObj.callOnce = false; } } else { - listenerObj = /** @type {ol.EventsKey} */ ({ + listenerObj = /** @type {module:ol/events~EventsKey} */ ({ bindTo: opt_this, callOnce: !!opt_once, listener: listener, @@ -151,19 +174,19 @@ export function listen(target, type, listener, opt_this, opt_once) { * * This function efficiently binds a `listener` as self-unregistering listener * to a `this` object, and returns a key for use with - * {@link ol.events.unlistenByKey} in case the listener needs to be unregistered - * before it is called. + * {@link module:ol/events~unlistenByKey} in case the listener needs to be + * unregistered before it is called. * - * When {@link ol.events.listen} is called with the same arguments after this + * When {@link module:ol/events~listen} is called with the same arguments after this * function, the self-unregistering listener will be turned into a permanent * listener. * - * @param {ol.EventTargetLike} target Event target. + * @param {module:ol/events/EventTarget~EventTargetLike} target Event target. * @param {string} type Event type. - * @param {ol.EventsListenerFunctionType} listener Listener. + * @param {module:ol/events~ListenerFunction} listener Listener. * @param {Object=} opt_this Object referenced by the `this` keyword in the * listener. Default is the `target`. - * @return {ol.EventsKey} Key for unlistenByKey. + * @return {module:ol/events~EventsKey} Key for unlistenByKey. */ export function listenOnce(target, type, listener, opt_this) { return listen(target, type, listener, opt_this, true); @@ -175,11 +198,11 @@ export function listenOnce(target, type, listener, opt_this) { * {@link https://google.github.io/closure-library/api/source/closure/goog/events/events.js.src.html} * * To return a listener, this function needs to be called with the exact same - * arguments that were used for a previous {@link ol.events.listen} call. + * arguments that were used for a previous {@link module:ol/events~listen} call. * - * @param {ol.EventTargetLike} target Event target. + * @param {module:ol/events/EventTarget~EventTargetLike} target Event target. * @param {string} type Event type. - * @param {ol.EventsListenerFunctionType} listener Listener. + * @param {module:ol/events~ListenerFunction} listener Listener. * @param {Object=} opt_this Object referenced by the `this` keyword in the * listener. Default is the `target`. */ @@ -199,9 +222,9 @@ export function unlisten(target, type, listener, opt_this) { * {@link https://google.github.io/closure-library/api/source/closure/goog/events/events.js.src.html} * * The argument passed to this function is the key returned from - * {@link ol.events.listen} or {@link ol.events.listenOnce}. + * {@link module:ol/events~listen} or {@link module:ol/events~listenOnce}. * - * @param {ol.EventsKey} key The key. + * @param {module:ol/events~EventsKey} key The key. */ export function unlistenByKey(key) { if (key && key.target) { @@ -225,7 +248,7 @@ export function unlistenByKey(key) { * Unregisters all event listeners on an event target. Inspired by * {@link https://google.github.io/closure-library/api/source/closure/goog/events/events.js.src.html} * - * @param {ol.EventTargetLike} target Target. + * @param {module:ol/events/EventTarget~EventTargetLike} target Target. */ export function unlistenAll(target) { const listenerMap = getListenerMap(target); diff --git a/src/ol/events/Event.js b/src/ol/events/Event.js index d998e624d1..464967361c 100644 --- a/src/ol/events/Event.js +++ b/src/ol/events/Event.js @@ -9,7 +9,7 @@ * This implementation only provides `type` and `target` properties, and * `stopPropagation` and `preventDefault` methods. It is meant as base class * for higher level events defined in the library, and works with - * {@link ol.events.EventTarget}. + * {@link module:ol/events/EventTarget~EventTarget}. * * @constructor * @implements {oli.events.Event} @@ -59,7 +59,7 @@ Event.prototype.preventDefault = /** - * @param {Event|ol.events.Event} evt Event + * @param {Event|module:ol/events/Event~Event} evt Event */ export function stopPropagation(evt) { evt.stopPropagation(); @@ -67,7 +67,7 @@ export function stopPropagation(evt) { /** - * @param {Event|ol.events.Event} evt Event + * @param {Event|module:ol/events/Event~Event} evt Event */ export function preventDefault(evt) { evt.preventDefault(); diff --git a/src/ol/events/EventTarget.js b/src/ol/events/EventTarget.js index 1823574e9d..a1088c7f05 100644 --- a/src/ol/events/EventTarget.js +++ b/src/ol/events/EventTarget.js @@ -7,6 +7,12 @@ import {unlistenAll} from '../events.js'; import {UNDEFINED} from '../functions.js'; import Event from '../events/Event.js'; + +/** + * @typedef {EventTarget|module:ol/events/EventTarget~EventTarget} EventTargetLike + */ + + /** * @classdesc * A simplified implementation of the W3C DOM Level 2 EventTarget interface. @@ -23,7 +29,7 @@ import Event from '../events/Event.js'; * returns false. * * @constructor - * @extends {ol.Disposable} + * @extends {module:ol/Disposable~Disposable} */ const EventTarget = function() { @@ -43,7 +49,7 @@ const EventTarget = function() { /** * @private - * @type {!Object.>} + * @type {!Object.>} */ this.listeners_ = {}; @@ -54,7 +60,7 @@ inherits(EventTarget, Disposable); /** * @param {string} type Type. - * @param {ol.EventsListenerFunctionType} listener Listener. + * @param {module:ol/events~ListenerFunction} listener Listener. */ EventTarget.prototype.addEventListener = function(type, listener) { let listeners = this.listeners_[type]; @@ -69,7 +75,7 @@ EventTarget.prototype.addEventListener = function(type, listener) { /** * @param {{type: string, - * target: (EventTarget|ol.events.EventTarget|undefined)}|ol.events.Event| + * target: (EventTarget|module:ol/events/EventTarget~EventTarget|undefined)}|module:ol/events/Event~Event| * string} event Event or event type. * @return {boolean|undefined} `false` if anyone called preventDefault on the * event object or if any of the listeners returned false. @@ -119,7 +125,7 @@ EventTarget.prototype.disposeInternal = function() { * order that they will be called in. * * @param {string} type Type. - * @return {Array.} Listeners. + * @return {Array.} Listeners. */ EventTarget.prototype.getListeners = function(type) { return this.listeners_[type]; @@ -140,7 +146,7 @@ EventTarget.prototype.hasListener = function(opt_type) { /** * @param {string} type Type. - * @param {ol.EventsListenerFunctionType} listener Listener. + * @param {module:ol/events~ListenerFunction} listener Listener. */ EventTarget.prototype.removeEventListener = function(type, listener) { const listeners = this.listeners_[type]; diff --git a/src/ol/events/EventType.js b/src/ol/events/EventType.js index 3e7689d36b..997f4181b5 100644 --- a/src/ol/events/EventType.js +++ b/src/ol/events/EventType.js @@ -9,7 +9,7 @@ export default { /** * Generic change event. Triggered when the revision counter is increased. - * @event ol.events.Event#change + * @event module:ol/events/Event~Event#change * @api */ CHANGE: 'change', diff --git a/src/ol/events/condition.js b/src/ol/events/condition.js index c280709650..3bee5ece34 100644 --- a/src/ol/events/condition.js +++ b/src/ol/events/condition.js @@ -11,7 +11,7 @@ import {WEBKIT, MAC} from '../has.js'; * Return `true` if only the alt-key is pressed, `false` otherwise (e.g. when * additionally the shift-key is pressed). * - * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent Map browser event. * @return {boolean} True if only the alt key is pressed. * @api */ @@ -28,7 +28,7 @@ export const altKeyOnly = function(mapBrowserEvent) { * Return `true` if only the alt-key and shift-key is pressed, `false` otherwise * (e.g. when additionally the platform-modifier-key is pressed). * - * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent Map browser event. * @return {boolean} True if only the alt and shift keys are pressed. * @api */ @@ -45,7 +45,7 @@ export const altShiftKeysOnly = function(mapBrowserEvent) { * Return `true` if the map has the focus. This condition requires a map target * element with a `tabindex` attribute, e.g. `
`. * - * @param {ol.MapBrowserEvent} event Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} event Map browser event. * @return {boolean} The map has the focus. * @api */ @@ -57,7 +57,7 @@ export const focus = function(event) { /** * Return always true. * - * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent Map browser event. * @return {boolean} True. * @function * @api @@ -68,7 +68,7 @@ export const always = TRUE; /** * Return `true` if the event is a `click` event, `false` otherwise. * - * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent Map browser event. * @return {boolean} True if the event is a map `click` event. * @api */ @@ -83,7 +83,7 @@ export const click = function(mapBrowserEvent) { * By definition, this includes left-click on windows/linux, and left-click * without the ctrl key on Macs. * - * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent Map browser event. * @return {boolean} The result. */ export const mouseActionButton = function(mapBrowserEvent) { @@ -96,7 +96,7 @@ export const mouseActionButton = function(mapBrowserEvent) { /** * Return always false. * - * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent Map browser event. * @return {boolean} False. * @function * @api @@ -108,7 +108,7 @@ export const never = FALSE; * Return `true` if the browser event is a `pointermove` event, `false` * otherwise. * - * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent Map browser event. * @return {boolean} True if the browser event is a `pointermove` event. * @api */ @@ -120,7 +120,7 @@ export const pointerMove = function(mapBrowserEvent) { /** * Return `true` if the event is a map `singleclick` event, `false` otherwise. * - * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent Map browser event. * @return {boolean} True if the event is a map `singleclick` event. * @api */ @@ -132,7 +132,7 @@ export const singleClick = function(mapBrowserEvent) { /** * Return `true` if the event is a map `dblclick` event, `false` otherwise. * - * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent Map browser event. * @return {boolean} True if the event is a map `dblclick` event. * @api */ @@ -145,7 +145,7 @@ export const doubleClick = function(mapBrowserEvent) { * Return `true` if no modifier key (alt-, shift- or platform-modifier-key) is * pressed. * - * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent Map browser event. * @return {boolean} True only if there no modifier keys are pressed. * @api */ @@ -163,7 +163,7 @@ export const noModifierKeys = function(mapBrowserEvent) { * ctrl-key otherwise) is pressed, `false` otherwise (e.g. when additionally * the shift-key is pressed). * - * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent Map browser event. * @return {boolean} True if only the platform modifier key is pressed. * @api */ @@ -179,7 +179,7 @@ export const platformModifierKeyOnly = function(mapBrowserEvent) { * Return `true` if only the shift-key is pressed, `false` otherwise (e.g. when * additionally the alt-key is pressed). * - * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event. + * @param {module:ol/MapBrowserEvent~MapBrowserEvent} mapBrowserEvent Map browser event. * @return {boolean} True if only the shift key is pressed. * @api */ @@ -196,7 +196,7 @@ export const shiftKeyOnly = function(mapBrowserEvent) { * Return `true` if the target element is not editable, i.e. not a ``-, * `