From 05c54177f0a48594e0957a73ed6aad0487d48a5a Mon Sep 17 00:00:00 2001 From: Colleen Date: Wed, 11 Sep 2019 21:09:08 -0700 Subject: [PATCH 1/8] add examples related to sources --- src/ui/map.js | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/src/ui/map.js b/src/ui/map.js index b93eef0940b..fa88fd08325 100755 --- a/src/ui/map.js +++ b/src/ui/map.js @@ -1144,9 +1144,29 @@ class Map extends Camera { * {@link CanvasSourceOptions}. * @fires source.add * @returns {Map} `this` - * @see [Draw GeoJSON points](https://www.mapbox.com/mapbox-gl-js/example/geojson-markers/) - * @see [Style circles using data-driven styling](https://www.mapbox.com/mapbox-gl-js/example/data-driven-circle-colors/) - * @see [Set a point after Geocoder result](https://www.mapbox.com/mapbox-gl-js/example/point-from-geocoder-result/) + * @example + * map.addSource('my-data', { + * type: 'vector', + * url: 'mapbox://myusername.tilesetid' + * }); + * @example + * map.addSource('my-data', { + * "type": "geojson", + * "data": { + * "type": "Feature", + * "geometry": { + * "type": "Point", + * "coordinates": [-77.0323, 38.9131] + * }, + * "properties": { + * "title": "Mapbox DC", + * "marker-symbol": "monument" + * } + * } + * }); + * @see Vector source: [Show and hide layers](https://docs.mapbox.com/mapbox-gl-js/example/toggle-layers/) + * @see GeoJSON source: [Add live realtime data](https://docs.mapbox.com/mapbox-gl-js/example/live-geojson/) + * @see Raster DEM source: [Add hillshading](https://docs.mapbox.com/mapbox-gl-js/example/hillshade/) */ addSource(id: string, source: SourceSpecification) { this.style.addSource(id, source); @@ -1158,6 +1178,8 @@ class Map extends Camera { * * @param {string} id The ID of the source to be checked. * @returns {boolean} A Boolean indicating whether the source is loaded. + * @example + * map.isSourceLoaded('bathymetry-data'); */ isSourceLoaded(id: string) { const source = this.style && this.style.sourceCaches[id]; @@ -1173,6 +1195,8 @@ class Map extends Camera { * the style are loaded. * * @returns {boolean} A Boolean indicating whether all tiles are loaded. + * @example + * map.areTilesLoaded(); */ areTilesLoaded() { @@ -1205,6 +1229,8 @@ class Map extends Camera { * * @param {string} id The ID of the source to remove. * @returns {Map} `this` + * @example + * map.removeSource('bathymetry-data') */ removeSource(id: string) { this.style.removeSource(id); @@ -1217,6 +1243,8 @@ class Map extends Camera { * @param {string} id The ID of the source to get. * @returns {?Object} The style source with the specified ID, or `undefined` * if the ID corresponds to no existing sources. + * @example + * var sourceId = map.getSource('points'); * @see [Create a draggable point](https://www.mapbox.com/mapbox-gl-js/example/drag-a-point/) * @see [Animate a point](https://www.mapbox.com/mapbox-gl-js/example/animate-point-along-line/) * @see [Add live realtime data](https://www.mapbox.com/mapbox-gl-js/example/live-geojson/) From e11ea66dbddeee8bbecb97b4cfbecf9bc63711b1 Mon Sep 17 00:00:00 2001 From: Colleen Date: Thu, 12 Sep 2019 18:52:52 -0700 Subject: [PATCH 2/8] add examples and rewrite descriptions related to images --- src/ui/map.js | 76 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 61 insertions(+), 15 deletions(-) diff --git a/src/ui/map.js b/src/ui/map.js index fa88fd08325..7495923bd81 100755 --- a/src/ui/map.js +++ b/src/ui/map.js @@ -1254,19 +1254,28 @@ class Map extends Camera { } /** - * Add an image to the style. This image can be used in `icon-image`, - * `background-pattern`, `fill-pattern`, and `line-pattern`. An - * {@link Map#error} event will be fired if there is not enough space in the - * sprite to add this image. + * Add an image to the style. This image can be displayed on the map like any other icon in the style's + * [sprite](https://docs.mapbox.com/help/glossary/sprite/) using the image's ID with + * [`icon-image`](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layout-symbol-icon-image), + * [`background-pattern`](https://docs.mapbox.com/mapbox-gl-js/style-spec/#paint-background-background-pattern), + * [`fill-pattern`](https://docs.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern), + * or [`line-pattern`](https://docs.mapbox.com/mapbox-gl-js/style-spec/#paint-line-line-pattern). + * A {@link Map#error} event will be fired if there is not enough space in the sprite to add this image. * - * @see [Add an icon to the map](https://www.mapbox.com/mapbox-gl-js/example/add-image/) - * @see [Add a generated icon to the map](https://www.mapbox.com/mapbox-gl-js/example/add-image-generated/) * @param id The ID of the image. * @param image The image as an `HTMLImageElement`, `ImageData`, or object with `width`, `height`, and `data` * properties with the same format as `ImageData`. * @param options * @param options.pixelRatio The ratio of pixels in the image to physical pixels on the screen * @param options.sdf Whether the image should be interpreted as an SDF image + * + * @example + * // If the style's sprite does not already contain an image with ID 'cat', + * // add the image 'cat-icon.png' to the style's sprite with the ID 'cat'. + * if (!map.hasImage('cat')) map.addImage('cat', './cat-icon.png'); + * + * @see Use `HTMLImageElement`: [Add an icon to the map](https://www.mapbox.com/mapbox-gl-js/example/add-image/) + * @see Use `ImageData`: [Add a generated icon to the map](https://www.mapbox.com/mapbox-gl-js/example/add-image-generated/) */ addImage(id: string, image: HTMLImageElement | ImageData | {width: number, height: number, data: Uint8Array | Uint8ClampedArray} | StyleImageInterface, @@ -1300,12 +1309,21 @@ class Map extends Camera { } /** - * Update an existing style image. This image can be used in `icon-image`, - * `background-pattern`, `fill-pattern`, and `line-pattern`. - * + * Update an existing image in a style. This image can be displayed on the map like any other icon in the style's + * [sprite](https://docs.mapbox.com/help/glossary/sprite/) using the image's ID with + * [`icon-image`](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layout-symbol-icon-image), + * [`background-pattern`](https://docs.mapbox.com/mapbox-gl-js/style-spec/#paint-background-background-pattern), + * [`fill-pattern`](https://docs.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern), + * or [`line-pattern`](https://docs.mapbox.com/mapbox-gl-js/style-spec/#paint-line-line-pattern). + * * @param id The ID of the image. * @param image The image as an `HTMLImageElement`, `ImageData`, or object with `width`, `height`, and `data` * properties with the same format as `ImageData`. + * + * @example + * // If an image with the ID 'cat' already exists in the style's sprite, + * // replace that image with a new image, 'other-cat-icon.png'. + * if (map.hasImage('cat')) map.updateImage('cat', './other-cat-icon.png'); */ updateImage(id: string, image: HTMLImageElement | ImageData | {width: number, height: number, data: Uint8Array | Uint8ClampedArray} | StyleImageInterface) { @@ -1337,9 +1355,16 @@ class Map extends Camera { } /** - * Define whether the image has been added or not - * + * Check whether or not an image with a specific ID exists in the style. This checks both images + * in the style's original [sprite](https://docs.mapbox.com/help/glossary/sprite/) and any images + * that have been added at runtime using {@link addImage}. + * * @param id The ID of the image. + * + * @example + * // Check if an image with the ID 'cat' exists in + * // the style's sprite. + * var catIconExists = map.hasImage('cat'); */ hasImage(id: string): boolean { if (!id) { @@ -1351,20 +1376,36 @@ class Map extends Camera { } /** - * Remove an image from the style (such as one used by `icon-image` or `background-pattern`). + * Remove an image from a style. This can be an image from the style's original + * [sprite](https://docs.mapbox.com/help/glossary/sprite/) or any images + * that have been added at runtime using {@link addImage}. * * @param id The ID of the image. + * + * @example + * // If an image with the ID 'cat' exists in + * // the style's sprite, remove it. + * if (map.hasImage('cat')) map.removeImage('cat'); */ removeImage(id: string) { this.style.removeImage(id); } /** - * Load an image from an external URL for use with `Map#addImage`. External + * Load an image from an external URL to be used with `Map#addImage`. External * domains must support [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS). * * @param {string} url The URL of the image file. Image file must be in png, webp, or jpg format. * @param {Function} callback Expecting `callback(error, data)`. Called when the image has loaded or with an error argument if there is an error. + * + * @example + * // Load an image from an external URL. + * map.loadImage('http://placekitten.com/50/50', function(error, image) { + * if (error) throw error; + * // Add the loaded image to the style's sprite with the ID 'kitten'. + * map.addImage('kitten', image); + * }); + * * @see [Add an icon to the map](https://www.mapbox.com/mapbox-gl-js/example/add-image/) */ loadImage(url: string, callback: Function) { @@ -1372,10 +1413,15 @@ class Map extends Camera { } /** - * Returns an Array of strings containing the names of all sprites/images currently available in the map + * Returns an Array of strings containing the IDs of all images currently available in the map. + * This includes both images from the style's original [sprite](https://docs.mapbox.com/help/glossary/sprite/) + * and any images that have been added at runtime using {@link addImage}. * - * @returns {Array} An Array of strings containing the names of all sprites/images currently available in the map + * @returns {Array} An Array of strings containing the names of all sprites/images currently available in the map. * + * @example + * var allImages = map.listImages(); + * */ listImages() { return this.style.listImages(); From 0f2b649d35540633ee7dcd606ae31bf867b8bd20 Mon Sep 17 00:00:00 2001 From: Colleen Date: Thu, 12 Sep 2019 21:11:44 -0700 Subject: [PATCH 3/8] add return for hasImage --- src/ui/map.js | 1 + 1 file changed, 1 insertion(+) diff --git a/src/ui/map.js b/src/ui/map.js index 7495923bd81..477664d054d 100755 --- a/src/ui/map.js +++ b/src/ui/map.js @@ -1361,6 +1361,7 @@ class Map extends Camera { * * @param id The ID of the image. * + * @returns {Boolean} A Boolean indicating whether the image exists. * @example * // Check if an image with the ID 'cat' exists in * // the style's sprite. From b7ee4f67feb8791cb09473b9818435c8076090fa Mon Sep 17 00:00:00 2001 From: Colleen Date: Fri, 13 Sep 2019 17:23:24 -0700 Subject: [PATCH 4/8] add examples related to layers --- src/ui/map.js | 82 +++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 63 insertions(+), 19 deletions(-) diff --git a/src/ui/map.js b/src/ui/map.js index 477664d054d..730005a4aff 100755 --- a/src/ui/map.js +++ b/src/ui/map.js @@ -1429,16 +1429,37 @@ class Map extends Camera { } /** - * Adds a [Mapbox style layer](https://www.mapbox.com/mapbox-gl-style-spec/#layers) + * Adds a [Mapbox style layer](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers) * to the map's style. * - * A layer defines styling for data from a specified source. + * A layer defines how data from a specified source will be styled. Read more about layer types + * and available paint and layout properties in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers). * * @param {Object | CustomLayerInterface} layer The style layer to add, conforming to the Mapbox Style Specification's - * [layer definition](https://www.mapbox.com/mapbox-gl-style-spec/#layers). + * [layer definition](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers). * @param {string} [beforeId] The ID of an existing layer to insert the new layer before. * If this argument is omitted, the layer will be appended to the end of the layers array. + * * @returns {Map} `this` + * + * @example + * // Add a circle layer with a vector source. + * map.addLayer({ + * id: 'points-of-interest', + * source: { + * type: 'vector', + * url: 'mapbox://mapbox.mapbox-streets-v8' + * }, + * 'source-layer': 'poi_label', + * type: 'circle', + * paint: { + * // Mapbox Style Specification paint properties + * }, + * layout: { + * // Mapbox Style Specification layout properties + * } + * }); + * * @see [Create and style clusters](https://www.mapbox.com/mapbox-gl-js/example/cluster/) * @see [Add a vector tile source](https://www.mapbox.com/mapbox-gl-js/example/vector-source/) * @see [Add a WMS source](https://www.mapbox.com/mapbox-gl-js/example/wms/) @@ -1455,6 +1476,10 @@ class Map extends Camera { * @param {string} [beforeId] The ID of an existing layer to insert the new layer before. * If this argument is omitted, the layer will be appended to the end of the layers array. * @returns {Map} `this` + * + * @example + * // Move a layer with ID 'label' before the layer with ID 'waterways'. + * map.moveLayer('label', 'waterways'); */ moveLayer(id: string, beforeId?: string) { this.style.moveLayer(id, beforeId); @@ -1462,12 +1487,16 @@ class Map extends Camera { } /** - * Removes the layer with the given id from the map's style. + * Removes the layer with the given ID from the map's style. * * If no such layer exists, an `error` event is fired. * * @param {string} id id of the layer to remove * @fires error + * + * @example + * // If a layer with ID 'state-data' exists, remove it. + * if (map.getLayer('state-data')) map.removeLayer('state-data'); */ removeLayer(id: string) { this.style.removeLayer(id); @@ -1480,6 +1509,10 @@ class Map extends Camera { * @param {string} id The ID of the layer to get. * @returns {?Object} The layer with the specified ID, or `undefined` * if the ID corresponds to no existing layers. + * + * @example + * var stateDataLayer = map.getLayer('state-data'); + * * @see [Filter symbols by toggling a list](https://www.mapbox.com/mapbox-gl-js/example/filter-markers/) * @see [Filter symbols by text input](https://www.mapbox.com/mapbox-gl-js/example/filter-markers-by-input/) */ @@ -1487,6 +1520,31 @@ class Map extends Camera { return this.style.getLayer(id); } + /** + * Sets the zoom extent for the specified style layer. The zoom extent includes the + * [minimum zoom level](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layer-minzoom) + * and [maximum zoom level](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layer-maxzoom)) + * at which the layer will be rendered. + * + * Note: For style layers using vector sources, style layers cannot be rendered at zoom levels lower than the + * minimum zoom level of the _source layer_ because the data does not exist at that zoom level. If the minimum + * zoom level of the source layer is higher than the minimum zoom level defined in the style layer, the style + * layer will not be rendered at all zoom levels in the zoom range. + * + * @param {string} layerId The ID of the layer to which the zoom extent will be applied. + * @param {number} minzoom The minimum zoom to set (0-24). + * @param {number} maxzoom The maximum zoom to set (0-24). + * @returns {Map} `this` + * + * @example + * map.setLayerZoomRange('my-layer', 2, 5); + * + */ + setLayerZoomRange(layerId: string, minzoom: number, maxzoom: number) { + this.style.setLayerZoomRange(layerId, minzoom, maxzoom); + return this._update(true); + } + /** * Sets the filter for the specified style layer. * @@ -1499,6 +1557,7 @@ class Map extends Camera { * @returns {Map} `this` * @example * map.setFilter('my-layer', ['==', 'name', 'USA']); + * * @see [Filter features within map view](https://www.mapbox.com/mapbox-gl-js/example/filter-features-within-map-view/) * @see [Highlight features containing similar data](https://www.mapbox.com/mapbox-gl-js/example/query-similar-features/) * @see [Create a timeline animation](https://www.mapbox.com/mapbox-gl-js/example/timeline-animation/) @@ -1508,21 +1567,6 @@ class Map extends Camera { return this._update(true); } - /** - * Sets the zoom extent for the specified style layer. - * - * @param {string} layerId The ID of the layer to which the zoom extent will be applied. - * @param {number} minzoom The minimum zoom to set (0-24). - * @param {number} maxzoom The maximum zoom to set (0-24). - * @returns {Map} `this` - * @example - * map.setLayerZoomRange('my-layer', 2, 5); - */ - setLayerZoomRange(layerId: string, minzoom: number, maxzoom: number) { - this.style.setLayerZoomRange(layerId, minzoom, maxzoom); - return this._update(true); - } - /** * Returns the filter applied to the specified style layer. * From f7b60f464854af848197b3d3d5c6e3cb07710c55 Mon Sep 17 00:00:00 2001 From: Colleen Date: Fri, 13 Sep 2019 17:28:16 -0700 Subject: [PATCH 5/8] fix linting errors --- src/ui/map.js | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/ui/map.js b/src/ui/map.js index 730005a4aff..07ec0527986 100755 --- a/src/ui/map.js +++ b/src/ui/map.js @@ -1268,7 +1268,7 @@ class Map extends Camera { * @param options * @param options.pixelRatio The ratio of pixels in the image to physical pixels on the screen * @param options.sdf Whether the image should be interpreted as an SDF image - * + * * @example * // If the style's sprite does not already contain an image with ID 'cat', * // add the image 'cat-icon.png' to the style's sprite with the ID 'cat'. @@ -1315,13 +1315,13 @@ class Map extends Camera { * [`background-pattern`](https://docs.mapbox.com/mapbox-gl-js/style-spec/#paint-background-background-pattern), * [`fill-pattern`](https://docs.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern), * or [`line-pattern`](https://docs.mapbox.com/mapbox-gl-js/style-spec/#paint-line-line-pattern). - * + * * @param id The ID of the image. * @param image The image as an `HTMLImageElement`, `ImageData`, or object with `width`, `height`, and `data` * properties with the same format as `ImageData`. * * @example - * // If an image with the ID 'cat' already exists in the style's sprite, + * // If an image with the ID 'cat' already exists in the style's sprite, * // replace that image with a new image, 'other-cat-icon.png'. * if (map.hasImage('cat')) map.updateImage('cat', './other-cat-icon.png'); */ @@ -1358,12 +1358,12 @@ class Map extends Camera { * Check whether or not an image with a specific ID exists in the style. This checks both images * in the style's original [sprite](https://docs.mapbox.com/help/glossary/sprite/) and any images * that have been added at runtime using {@link addImage}. - * + * * @param id The ID of the image. * - * @returns {Boolean} A Boolean indicating whether the image exists. + * @returns {boolean} A Boolean indicating whether the image exists. * @example - * // Check if an image with the ID 'cat' exists in + * // Check if an image with the ID 'cat' exists in * // the style's sprite. * var catIconExists = map.hasImage('cat'); */ @@ -1382,9 +1382,9 @@ class Map extends Camera { * that have been added at runtime using {@link addImage}. * * @param id The ID of the image. - * + * * @example - * // If an image with the ID 'cat' exists in + * // If an image with the ID 'cat' exists in * // the style's sprite, remove it. * if (map.hasImage('cat')) map.removeImage('cat'); */ @@ -1406,7 +1406,7 @@ class Map extends Camera { * // Add the loaded image to the style's sprite with the ID 'kitten'. * map.addImage('kitten', image); * }); - * + * * @see [Add an icon to the map](https://www.mapbox.com/mapbox-gl-js/example/add-image/) */ loadImage(url: string, callback: Function) { @@ -1422,7 +1422,7 @@ class Map extends Camera { * * @example * var allImages = map.listImages(); - * + * */ listImages() { return this.style.listImages(); From 0e4162078b2342fb4935ba7462b391d493ee230c Mon Sep 17 00:00:00 2001 From: Colleen Date: Fri, 13 Sep 2019 17:39:05 -0700 Subject: [PATCH 6/8] clean up --- src/ui/map.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/ui/map.js b/src/ui/map.js index 07ec0527986..4ba48b81656 100755 --- a/src/ui/map.js +++ b/src/ui/map.js @@ -1179,7 +1179,7 @@ class Map extends Camera { * @param {string} id The ID of the source to be checked. * @returns {boolean} A Boolean indicating whether the source is loaded. * @example - * map.isSourceLoaded('bathymetry-data'); + * var sourceLoaded = map.isSourceLoaded('bathymetry-data'); */ isSourceLoaded(id: string) { const source = this.style && this.style.sourceCaches[id]; @@ -1196,7 +1196,7 @@ class Map extends Camera { * * @returns {boolean} A Boolean indicating whether all tiles are loaded. * @example - * map.areTilesLoaded(); + * var tilesLoaded = map.areTilesLoaded(); */ areTilesLoaded() { @@ -1230,7 +1230,7 @@ class Map extends Camera { * @param {string} id The ID of the source to remove. * @returns {Map} `this` * @example - * map.removeSource('bathymetry-data') + * map.removeSource('bathymetry-data'); */ removeSource(id: string) { this.style.removeSource(id); From 1b4609e48b61ce6dc3f1b04bb8b97b3d3ac2790b Mon Sep 17 00:00:00 2001 From: Colleen Date: Fri, 13 Sep 2019 17:49:19 -0700 Subject: [PATCH 7/8] adjust getSource example --- src/ui/map.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ui/map.js b/src/ui/map.js index 4ba48b81656..b142f5e636d 100755 --- a/src/ui/map.js +++ b/src/ui/map.js @@ -1244,7 +1244,7 @@ class Map extends Camera { * @returns {?Object} The style source with the specified ID, or `undefined` * if the ID corresponds to no existing sources. * @example - * var sourceId = map.getSource('points'); + * var sourceObject = map.getSource('points'); * @see [Create a draggable point](https://www.mapbox.com/mapbox-gl-js/example/drag-a-point/) * @see [Animate a point](https://www.mapbox.com/mapbox-gl-js/example/animate-point-along-line/) * @see [Add live realtime data](https://www.mapbox.com/mapbox-gl-js/example/live-geojson/) From 83c56e540c6eee4320ee7fe20699fa37859e4ed7 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Tue, 17 Sep 2019 13:08:04 -0700 Subject: [PATCH 8/8] Update src/ui/map.js --- src/ui/map.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ui/map.js b/src/ui/map.js index b142f5e636d..7403fd90bcc 100755 --- a/src/ui/map.js +++ b/src/ui/map.js @@ -1527,7 +1527,7 @@ class Map extends Camera { * at which the layer will be rendered. * * Note: For style layers using vector sources, style layers cannot be rendered at zoom levels lower than the - * minimum zoom level of the _source layer_ because the data does not exist at that zoom level. If the minimum + * minimum zoom level of the _source layer_ because the data does not exist at those zoom levels. If the minimum * zoom level of the source layer is higher than the minimum zoom level defined in the style layer, the style * layer will not be rendered at all zoom levels in the zoom range. *