diff --git a/src/geo/lng_lat.js b/src/geo/lng_lat.js index 971214994a3..e978f348cee 100644 --- a/src/geo/lng_lat.js +++ b/src/geo/lng_lat.js @@ -12,8 +12,10 @@ export const earthRadius = 6371008.8; /** * A `LngLat` object represents a given longitude and latitude coordinate, measured in degrees. + * These coordinates are based on the [WGS84 (EPSG:4326) standard](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84). * - * Mapbox GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON. + * Mapbox GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match the + * [GeoJSON specification](https://tools.ietf.org/html/rfc7946). * * Note that any Mapbox GL method that accepts a `LngLat` object as an argument or option * can also accept an `Array` of two numbers and will perform an implicit conversion. @@ -22,7 +24,8 @@ export const earthRadius = 6371008.8; * @param {number} lng Longitude, measured in degrees. * @param {number} lat Latitude, measured in degrees. * @example - * var ll = new mapboxgl.LngLat(-73.9749, 40.7736); + * var ll = new mapboxgl.LngLat(-123.9749, 40.7736); + * ll.lng; // = -123.9749 * @see [Get coordinates of the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/mouse-position/) * @see [Display a popup](https://www.mapbox.com/mapbox-gl-js/example/popup/) * @see [Highlight features within a bounding box](https://www.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/) diff --git a/src/geo/lng_lat_bounds.js b/src/geo/lng_lat_bounds.js index 7fbf4db9c4a..f2360e96db6 100644 --- a/src/geo/lng_lat_bounds.js +++ b/src/geo/lng_lat_bounds.js @@ -216,6 +216,15 @@ class LngLatBounds { * * @param {LngLatLike} lnglat geographic point to check against. * @returns {boolean} True if the point is within the bounding box. + * @example + * var llb = new mapboxgl.LngLatBounds( + * new mapboxgl.LngLat(-73.9876, 40.7661), + * new mapboxgl.LngLat(-73.9397, 40.8002) + * ); + * + * var ll = new mapboxgl.LngLat(-73.9567, 40.7789); + * + * console.log(llb.contains(ll)); // = true */ contains(lnglat: LngLatLike) { const {lng, lat} = LngLat.convert(lnglat); diff --git a/src/index.js b/src/index.js index c85f5def198..bdc8b97f348 100644 --- a/src/index.js +++ b/src/index.js @@ -163,6 +163,8 @@ const exported = { * * @function clearStorage * @param {Function} callback Called with an error argument if there is an error. + * @example + * mapboxgl.clearStorage(); */ clearStorage(callback?: (err: ?Error) => void) { clearTileCache(callback); diff --git a/src/source/geojson_source.js b/src/source/geojson_source.js index 2b043f1ef91..67cfab6f8a8 100644 --- a/src/source/geojson_source.js +++ b/src/source/geojson_source.js @@ -230,6 +230,22 @@ class GeoJSONSource extends Evented implements Source { * @param offset The number of features to skip (e.g. for pagination). * @param callback A callback to be called when the features are retrieved (`(error, features) => { ... }`). * @returns {GeoJSONSource} this + * @example + * // Retrieve cluster leaves on click + * map.on('click', 'clusters', function(e) { + * var features = map.queryRenderedFeatures(e.point, { + * layers: ['clusters'] + * }); + * + * var clusterId = features[0].properties.cluster_id; + * var pointCount = features[0].properties.point_count; + * var clusterSource = map.getSource('clusters'); + * + * clusterSource.getClusterLeaves(clusterId, pointCount, 0, function(error, features) { + * // Print cluster leaves in the console + * console.log('Cluster leaves:', error, features); + * }) + * }); */ getClusterLeaves(clusterId: number, limit: number, offset: number, callback: Callback>) { this.actor.send('geojson.getClusterLeaves', { diff --git a/src/ui/camera.js b/src/ui/camera.js index e78443f14d9..40bfad0dc9e 100644 --- a/src/ui/camera.js +++ b/src/ui/camera.js @@ -33,11 +33,28 @@ import type {PaddingOptions} from '../geo/edge_insets'; * @typedef {Object} CameraOptions * @property {LngLatLike} center The desired center. * @property {number} zoom The desired zoom level. - * @property {number} bearing The desired bearing, in degrees. The bearing is the compass direction that - * is "up"; for example, a bearing of 90° orients the map so that east is up. - * @property {number} pitch The desired pitch, in degrees. + * @property {number} bearing The desired bearing in degrees. The bearing is the compass direction that + * is "up". For example, `bearing: 90` orients the map so that east is up. + * @property {number} pitch The desired pitch in degrees. The pitch is the angle towards the horizon + * measured in degrees with a range between 0 and 60 degrees. For example, pitch: 0 provides the appearance + * of looking straight down at the map, while pitch: 60 tilts the user's perspective towards the horizon. + * Increasing the pitch value is often used to display 3D objects. * @property {LngLatLike} around If `zoom` is specified, `around` determines the point around which the zoom is centered. * @property {PaddingOptions} padding Dimensions in pixels applied on each side of the viewport for shifting the vanishing point. + * @example + * // set the map's initial perspective with CameraOptions + * var map = new mapboxgl.Map({ + * container: 'map', + * style: 'mapbox://styles/mapbox/streets-v11', + * center: [-73.5804, 45.53483], + * pitch: 60, + * bearing: -60, + * zoom: 10 + * }); + * @see [Set pitch and bearing](https://docs.mapbox.com/mapbox-gl-js/example/set-perspective/) + * @see [Jump to a series of locations](https://docs.mapbox.com/mapbox-gl-js/example/jump-to/) + * @see [Fly to a location](https://docs.mapbox.com/mapbox-gl-js/example/flyto/) + * @see [Display buildings in 3D](https://docs.mapbox.com/mapbox-gl-js/example/3d-buildings/) */ export type CameraOptions = { center?: LngLatLike, @@ -71,7 +88,7 @@ export type AnimationOptions = { }; /** - * Options for setting padding on a call to {@link Map#fitBounds}. All properties of this object must be + * Options for setting padding on calls to methods such as {@link Map#fitBounds}, {@link Map#fitScreenCoordinates}, and {@link Map#setPadding}. Adjust these options to set the amount of padding in pixels added to the edges of the canvas. Set a uniform padding on all edges or individual values for each edge. All properties of this object must be * non-negative integers. * * @typedef {Object} PaddingOptions @@ -79,6 +96,20 @@ export type AnimationOptions = { * @property {number} bottom Padding in pixels from the bottom of the map canvas. * @property {number} left Padding in pixels from the left of the map canvas. * @property {number} right Padding in pixels from the right of the map canvas. + * + * @example + * var bbox = [[-79, 43], [-73, 45]]; + * map.fitBounds(bbox, { + * padding: {top: 10, bottom:25, left: 15, right: 5} + * }); + * + * @example + * var bbox = [[-79, 43], [-73, 45]]; + * map.fitBounds(bbox, { + * padding: 20 + * }); + * @see [Fit to the bounds of a LineString](https://docs.mapbox.com/mapbox-gl-js/example/zoomto-linestring/) + * @see [Fit a map to a bounding box](https://docs.mapbox.com/mapbox-gl-js/example/fitbounds/) */ class Camera extends Evented { @@ -119,6 +150,12 @@ class Camera extends Evented { * * @memberof Map# * @returns The map's geographical centerpoint. + * @example + * // return a LngLat object such as {lng: 0, lat: 0} + * var center = map.getCenter(); + * // access longitude and latitude values directly + * var {longitude, latitude} = map.getCenter(); + * @see Tutorial: [Use Mapbox GL JS in a React app](https://docs.mapbox.com/help/tutorials/use-mapbox-gl-js-with-react/#store-the-new-coordinates) */ getCenter(): LngLat { return new LngLat(this.transform.center.lng, this.transform.center.lat); } @@ -156,15 +193,21 @@ class Camera extends Evented { } /** - * Pans the map to the specified location, with an animated transition. + * Pans the map to the specified location with an animated transition. * * @memberof Map# * @param lnglat The location to pan the map to. - * @param options Options object + * @param options Options describing the destination and animation of the transition. * @param eventData Additional properties to be added to event objects of events triggered by this method. * @fires movestart * @fires moveend * @returns {Map} `this` + * @example + * map.panTo([-74, 38]); + * @example + * // Specify that the panTo animation should last 5000 milliseconds. + * map.panTo([-74, 38], {duration: 5000}); + * @see [Update a feature in realtime](https://docs.mapbox.com/mapbox-gl-js/example/live-update-feature/) */ panTo(lnglat: LngLatLike, options?: AnimationOptions, eventData?: Object) { return this.easeTo(extend({ @@ -177,6 +220,8 @@ class Camera extends Evented { * * @memberof Map# * @returns The map's current zoom level. + * @example + * map.getZoom(); */ getZoom(): number { return this.transform.zoom; } @@ -194,7 +239,7 @@ class Camera extends Evented { * @fires zoomend * @returns {Map} `this` * @example - * // zoom the map to 5 + * // Zoom to the zoom level 5 without an animated transition * map.setZoom(5); */ setZoom(zoom: number, eventData?: Object) { @@ -216,6 +261,14 @@ class Camera extends Evented { * @fires moveend * @fires zoomend * @returns {Map} `this` + * @example + * // Zoom to the zoom level 5 without an animated transition + * map.zoomTo(5); + * // Zoom to the zoom level 8 with an animated transition + * map.zoomTo(8, { + * duration: 2000, + * offset: [100, 50] + * }); */ zoomTo(zoom: number, options: ? AnimationOptions, eventData?: Object) { return this.easeTo(extend({ @@ -236,6 +289,9 @@ class Camera extends Evented { * @fires moveend * @fires zoomend * @returns {Map} `this` + * @example + * // zoom the map in one level with a custom animation duration + * map.zoomIn({duration: 1000}); */ zoomIn(options?: AnimationOptions, eventData?: Object) { this.zoomTo(this.getZoom() + 1, options, eventData); @@ -255,6 +311,9 @@ class Camera extends Evented { * @fires moveend * @fires zoomend * @returns {Map} `this` + * @example + * // zoom the map out one level with a custom animation offset + * map.zoomOut({offset: [80, 60]}); */ zoomOut(options?: AnimationOptions, eventData?: Object) { this.zoomTo(this.getZoom() - 1, options, eventData); @@ -631,6 +690,18 @@ class Camera extends Evented { * @fires zoomend * @fires pitchend * @returns {Map} `this` + * @example + * // jump to coordinates at current zoom + * map.jumpTo({center: [0, 0]}); + * // jump with zoom, pitch, and bearing options + * map.jumpTo({ + * center: [0, 0], + * zoom: 8, + * pitch: 45, + * bearing: 90 + * }); + * @see [Jump to a series of locations](https://docs.mapbox.com/mapbox-gl-js/example/jump-to/) + * @see [Update a feature in realtime](https://docs.mapbox.com/mapbox-gl-js/example/live-update-feature/) */ jumpTo(options: CameraOptions, eventData?: Object) { this.stop(); diff --git a/src/ui/control/geolocate_control.js b/src/ui/control/geolocate_control.js index 0e5f5e80736..87a39f3848f 100644 --- a/src/ui/control/geolocate_control.js +++ b/src/ui/control/geolocate_control.js @@ -406,10 +406,23 @@ class GeolocateControl extends Evented { } /** - * Trigger a geolocation - * - * @returns {boolean} Returns `false` if called before control was added to a map, otherwise returns `true`. - */ + * Programmatically request and move the map to the user's location. + * + * @returns {boolean} Returns `false` if called before control was added to a map, otherwise returns `true`. + * @example + * // Initialize the geolocate control. + * var geolocate = new mapboxgl.GeolocateControl({ + * positionOptions: { + * enableHighAccuracy: true + * }, + * trackUserLocation: true + * }); + * // Add the control to the map. + * map.addControl(geolocate); + * map.on('load', function() { + * geolocate.trigger(); + * }); + */ trigger() { if (!this._setup) { warnOnce('Geolocate control triggered before added to a map'); @@ -552,6 +565,21 @@ export default GeolocateControl; * @memberof GeolocateControl * @instance * @property {Position} data The returned [Position](https://developer.mozilla.org/en-US/docs/Web/API/Position) object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition) or [Geolocation.watchPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition). + * @example + * // Initialize the geolocate control. + * var geolocate = new mapboxgl.GeolocateControl({ + * positionOptions: { + * enableHighAccuracy: true + * }, + * trackUserLocation: true + * }); + * // Add the control to the map. + * map.addControl(geolocate); + * // Set an event listener that fires + * // when a geolocate event occurs. + * geolocate.on('geolocate', function() { + * console.log('A geolocate event has occurred.') + * }); * */ @@ -562,6 +590,21 @@ export default GeolocateControl; * @memberof GeolocateControl * @instance * @property {PositionError} data The returned [PositionError](https://developer.mozilla.org/en-US/docs/Web/API/PositionError) object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition) or [Geolocation.watchPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition). + * @example + * // Initialize the geolocate control. + * var geolocate = new mapboxgl.GeolocateControl({ + * positionOptions: { + * enableHighAccuracy: true + * }, + * trackUserLocation: true + * }); + * // Add the control to the map. + * map.addControl(geolocate); + * // Set an event listener that fires + * // when an error event occurs. + * geolocate.on('error', function() { + * console.log('An error event has occurred.') + * }); * */ @@ -572,6 +615,21 @@ export default GeolocateControl; * @memberof GeolocateControl * @instance * @property {Position} data The returned [Position](https://developer.mozilla.org/en-US/docs/Web/API/Position) object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition) or [Geolocation.watchPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition). + * @example + * // Initialize the geolocate control. + * var geolocate = new mapboxgl.GeolocateControl({ + * positionOptions: { + * enableHighAccuracy: true + * }, + * trackUserLocation: true + * }); + * // Add the control to the map. + * map.addControl(geolocate); + * // Set an event listener that fires + * // when an outofmaxbounds event occurs. + * geolocate.on('outofmaxbounds', function() { + * console.log('An outofmaxbounds event has occurred.') + * }); * */ @@ -581,6 +639,21 @@ export default GeolocateControl; * @event trackuserlocationstart * @memberof GeolocateControl * @instance + * @example + * // Initialize the geolocate control. + * var geolocate = new mapboxgl.GeolocateControl({ + * positionOptions: { + * enableHighAccuracy: true + * }, + * trackUserLocation: true + * }); + * // Add the control to the map. + * map.addControl(geolocate); + * // Set an event listener that fires + * // when a trackuserlocationstart event occurs. + * geolocate.on('trackuserlocationstart', function() { + * console.log('A trackuserlocationstart event has occurred.') + * }); * */ @@ -590,5 +663,20 @@ export default GeolocateControl; * @event trackuserlocationend * @memberof GeolocateControl * @instance + * @example + * // Initialize the geolocate control. + * var geolocate = new mapboxgl.GeolocateControl({ + * positionOptions: { + * enableHighAccuracy: true + * }, + * trackUserLocation: true + * }); + * // Add the control to the map. + * map.addControl(geolocate); + * // Set an event listener that fires + * // when a trackuserlocationend event occurs. + * geolocate.on('trackuserlocationend', function() { + * console.log('A trackuserlocationend event has occurred.') + * }); * */ diff --git a/src/ui/events.js b/src/ui/events.js index cf261c396fb..66abb6d81fd 100644 --- a/src/ui/events.js +++ b/src/ui/events.js @@ -12,10 +12,27 @@ import type LngLat from '../geo/lng_lat'; /** * `MapMouseEvent` is the event type for mouse-related map events. * @extends {Object} + * @example + * // The `click` event is an example of a `MapMouseEvent`. + * // Set up an event listener on the map. + * map.on('click', function(e) { + * // The event object (e) contains information like the + * // coordinates of the point on the map that was clicked. + * console.log('A click event has occurred at ' + e.lngLat); + * }); */ export class MapMouseEvent extends Event { /** - * The event type. + * The event type (one of [`mousedown`](#map.event:mousedown), + * [`mouseup`](#map.event:mouseup), + * [`click`](#map.event:click), + * [`dblclick`](#map.event:dblclick), + * [`mousemove`](#map.event:mousemove), + * [`mouseover`](#map.event:mouseover), + * [`mouseenter`](#map.event:mouseenter), + * [`mouseleave`](#map.event:mouseleave), + * [`mouseout`](#map.event:mouseout), + * [`contextmenu`](#map.event:contextmenu)). */ type: 'mousedown' | 'mouseup' @@ -218,17 +235,18 @@ export class MapWheelEvent extends Event { } /** - * A `MapBoxZoomEvent` is the event type for boxzoom-related map events. - * `originalEvent` can be a {@link Map.event:click} when the zoom is triggered by a UI event. + * A `MapBoxZoomEvent` is the event type for the boxzoom-related map events emitted by the {@link BoxZoomHandler}. * * @typedef {Object} MapBoxZoomEvent - * @property {MouseEvent} originalEvent + * @property {MouseEvent} originalEvent The DOM event that triggered the boxzoom event. Can be a `MouseEvent` or `KeyboardEvent` + * @property {string} type The type of boxzoom event. One of `boxzoomstart`, `boxzoomend` or `boxzoomcancel` + * @property {Map} target The `Map` instance that triggerred the event */ export type MapBoxZoomEvent = { type: 'boxzoomstart' | 'boxzoomend' | 'boxzoomcancel', - map: Map, + target: Map, originalEvent: MouseEvent }; @@ -251,6 +269,14 @@ export type MapBoxZoomEvent = { * the event is related to loading of a tile. * @property {Coordinate} [coord] The coordinate of the tile if the event has a `dataType` of `source` and * the event is related to loading of a tile. + * @example + * // The sourcedata event is an example of MapDataEvent. + * // Set up an event listener on the map. + * map.on('sourcedata', function(e) { + * if (e.isSourceLoaded) { + * // Do something when the source has finished loading + * } + * }); */ export type MapDataEvent = { type: string, @@ -266,34 +292,90 @@ export type MapEvent = /** * Fired when a pointing device (usually a mouse) is pressed within the map. * + * **Note:** This event is compatible with the optional `layerId` parameter. + * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the + * the cursor is pressed while inside a visible portion of the specifed layer. + * * @event mousedown * @memberof Map * @instance * @property {MapMouseEvent} data - * @see [Highlight features within a bounding box](https://www.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/) - * @see [Create a draggable point](https://www.mapbox.com/mapbox-gl-js/example/drag-a-point/) + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener + * map.on('mousedown', function() { + * console.log('A mousedown event has occurred.'); + * }); + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener for a specific layer + * map.on('mousedown', 'poi-label', function() { + * console.log('A mousedown event has occurred on a visible portion of the poi-label layer.'); + * }); + * @see [Highlight features within a bounding box](https://docs.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/) + * @see [Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/) */ | 'mousedown' /** * Fired when a pointing device (usually a mouse) is released within the map. * + * **Note:** This event is compatible with the optional `layerId` parameter. + * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the + * the cursor is released while inside a visible portion of the specifed layer. + * * @event mouseup * @memberof Map * @instance * @property {MapMouseEvent} data - * @see [Highlight features within a bounding box](https://www.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/) - * @see [Create a draggable point](https://www.mapbox.com/mapbox-gl-js/example/drag-a-point/) + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener + * map.on('mouseup', function() { + * console.log('A mouseup event has occurred.'); + * }); + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener for a specific layer + * map.on('mouseup', 'poi-label', function() { + * console.log('A mouseup event has occurred on a visible portion of the poi-label layer.'); + * }); + * @see [Highlight features within a bounding box](https://docs.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/) + * @see [Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/) */ | 'mouseup' /** * Fired when a pointing device (usually a mouse) is moved within the map. + * As you move the cursor across a web page containing a map, + * the event will fire each time it enters the map or any child elements. + * + * **Note:** This event is compatible with the optional `layerId` parameter. + * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the + * the cursor is moved inside a visible portion of the specifed layer. * * @event mouseover * @memberof Map * @instance * @property {MapMouseEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener + * map.on('mouseover', function() { + * console.log('A mouseover event has occurred.'); + * }); + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener for a specific layer + * map.on('mouseover', 'poi-label', function() { + * console.log('A mouseover event has occurred on a visible portion of the poi-label layer.'); + * }); * @see [Get coordinates of the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/mouse-position/) * @see [Highlight features under the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/hover-styles/) * @see [Display a popup on hover](https://www.mapbox.com/mapbox-gl-js/example/popup-on-hover/) @@ -301,12 +383,31 @@ export type MapEvent = | 'mouseover' /** - * Fired when a pointing device (usually a mouse) is moved within the map. + * Fired when a pointing device (usually a mouse) is moved while the cursor is inside the map. + * As you move the cursor across the map, the event will fire every time the cursor changes position within the map. + * + * **Note:** This event is compatible with the optional `layerId` parameter. + * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the + * the cursor is inside a visible portion of the specified layer. * * @event mousemove * @memberof Map * @instance * @property {MapMouseEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener + * map.on('mousemove', function() { + * console.log('A mousemove event has occurred.'); + * }); + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener for a specific layer + * map.on('mousemove', 'poi-label', function() { + * console.log('A mousemove event has occurred on a visible portion of the poi-label layer.'); + * }); * @see [Get coordinates of the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/mouse-position/) * @see [Highlight features under the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/hover-styles/) * @see [Display a popup on over](https://www.mapbox.com/mapbox-gl-js/example/popup-on-hover/) @@ -316,47 +417,107 @@ export type MapEvent = /** * Fired when a pointing device (usually a mouse) is pressed and released at the same point on the map. * + * **Note:** This event is compatible with the optional `layerId` parameter. + * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the + * point that is pressed and released contains a visible portion of the specifed layer. + * * @event click * @memberof Map * @instance * @property {MapMouseEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener + * map.on('click', function(e) { + * console.log('A click event has occurred at ' + e.lngLat); + * }); + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener for a specific layer + * map.on('click', 'poi-label', function(e) { + * console.log('A click event has occurred on a visible portion of the poi-label layer at ' + e.lngLat); + * }); * @see [Measure distances](https://www.mapbox.com/mapbox-gl-js/example/measure/) * @see [Center the map on a clicked symbol](https://www.mapbox.com/mapbox-gl-js/example/center-on-symbol/) */ | 'click' /** - * Fired when a pointing device (usually a mouse) is clicked twice at the same point on the map. + * Fired when a pointing device (usually a mouse) is pressed and released twice at the same point on + * the map in rapid succession. + * + * **Note:** This event is compatible with the optional `layerId` parameter. + * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only + * when the point that is clicked twice contains a visible portion of the specifed layer. * * @event dblclick * @memberof Map * @instance * @property {MapMouseEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener + * map.on('dblclick', function(e) { + * console.log('A dblclick event has occurred at ' + e.lngLat); + * }); + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener for a specific layer + * map.on('dblclick', 'poi-label', function(e) { + * console.log('A dblclick event has occurred on a visible portion of the poi-label layer at ' + e.lngLat); + * }); */ | 'dblclick' /** * Fired when a pointing device (usually a mouse) enters a visible portion of a specified layer from - * outside that layer or outside the map canvas. This event can only be listened for via the three-argument - * version of {@link Map#on}, where the second argument specifies the desired layer. + * outside that layer or outside the map canvas. + * + * **Important:** This event can only be listened for when {@link Map#on} includes three arguements, + * where the second argument specifies the desired layer. * * @event mouseenter * @memberof Map * @instance * @property {MapMouseEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener + * map.on('mouseenter', 'water', function() { + * console.log('A mouseenter event occurred on a visible portion of the water layer.'); + * }); + * @see [Center the map on a clicked symbol](https://docs.mapbox.com/mapbox-gl-js/example/center-on-symbol/) + * @see [Display a popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/) */ | 'mouseenter' /** * Fired when a pointing device (usually a mouse) leaves a visible portion of a specified layer, or leaves - * the map canvas. This event can only be listened for via the three-argument version of {@link Map#on}, + * the map canvas. + * + * **Important:** This event can only be listened for when {@link Map#on} includes three arguements, * where the second argument specifies the desired layer. * * @event mouseleave * @memberof Map * @instance * @property {MapMouseEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when the pointing device leaves + * // a visible portion of the specified layer. + * map.on('mouseleave', 'water', function() { + * console.log('A mouseleave event occurred.'); + * }); * @see [Highlight features under the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/hover-styles/) + * @see [Display a popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/) */ | 'mouseleave' @@ -367,6 +528,15 @@ export type MapEvent = * @memberof Map * @instance * @property {MapMouseEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when the pointing device leave's + * // the map's canvas. + * map.on('mouseout', function() { + * console.log('A mouseout event occurred.'); + * }); */ | 'mouseout' @@ -377,6 +547,15 @@ export type MapEvent = * @memberof Map * @instance * @property {MapMouseEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when the right mouse button is + * // pressed within the map. + * map.on('contextmenu', function() { + * console.log('A contextmenu event occurred.'); + * }); */ | 'contextmenu' @@ -387,6 +566,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapWheelEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when a wheel event occurs within the map. + * map.on('wheel', function() { + * console.log('A wheel event occurred.'); + * }); */ | 'wheel' @@ -397,6 +584,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapTouchEvent} data + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when a touchstart event occurs within the map. + * map.on('touchstart', function() { + * console.log('A touchstart event occurred.'); + * }); + * @see [Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/) */ | 'touchstart' @@ -407,6 +602,15 @@ export type MapEvent = * @memberof Map * @instance * @property {MapTouchEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when a touchstart event occurs within the map. + * map.on('touchstart', function() { + * console.log('A touchstart event occurred.'); + * }); + * @see [Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/) */ | 'touchend' @@ -417,6 +621,15 @@ export type MapEvent = * @memberof Map * @instance * @property {MapTouchEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when a touchmove event occurs within the map. + * map.on('touchmove', function() { + * console.log('A touchmove event occurred.'); + * }); + * @see [Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/) */ | 'touchmove' @@ -427,6 +640,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapTouchEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when a touchcancel event occurs within the map. + * map.on('touchcancel', function() { + * console.log('A touchcancel event occurred.'); + * }); */ | 'touchcancel' @@ -438,6 +659,15 @@ export type MapEvent = * @memberof Map * @instance * @property {{originalEvent: DragEvent}} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // just before the map begins a transition + * // from one view to another. + * map.on('movestart', function() { + * console.log('A movestart` event occurred.'); + * }); */ | 'movestart' @@ -449,6 +679,16 @@ export type MapEvent = * @memberof Map * @instance * @property {MapMouseEvent | MapTouchEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // repeatedly during an animated transition. + * map.on('move', function() { + * console.log('A move event occurred.'); + * }); + * @see [Display HTML clusters with custom properties](https://docs.mapbox.com/mapbox-gl-js/example/cluster-html/) + * @see [Filter features within map view](https://docs.mapbox.com/mapbox-gl-js/example/filter-features-within-map-view/) */ | 'move' @@ -460,8 +700,17 @@ export type MapEvent = * @memberof Map * @instance * @property {{originalEvent: DragEvent}} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // just after the map completes a transition. + * map.on('moveend', function() { + * console.log('A moveend event occurred.'); + * }); * @see [Play map locations as a slideshow](https://www.mapbox.com/mapbox-gl-js/example/playback-locations/) * @see [Filter features within map view](https://www.mapbox.com/mapbox-gl-js/example/filter-features-within-map-view/) + * @see [Display HTML clusters with custom properties](https://docs.mapbox.com/mapbox-gl-js/example/cluster-html/) */ | 'moveend' @@ -472,6 +721,14 @@ export type MapEvent = * @memberof Map * @instance * @property {{originalEvent: DragEvent}} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when a "drag to pan" interaction starts. + * map.on('dragstart', function() { + * console.log('A dragstart event occurred.'); + * }); */ | 'dragstart' @@ -482,6 +739,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapMouseEvent | MapTouchEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // repeatedly during a "drag to pan" interaction. + * map.on('drag', function() { + * console.log('A drag event occurred.'); + * }); */ | 'drag' @@ -492,6 +757,15 @@ export type MapEvent = * @memberof Map * @instance * @property {{originalEvent: DragEvent}} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when a "drag to pan" interaction ends. + * map.on('dragend', function() { + * console.log('A dragend event occurred.'); + * }); + * @see [Create a draggable marker](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-marker/) */ | 'dragend' @@ -503,6 +777,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapMouseEvent | MapTouchEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // just before a zoom transition starts. + * map.on('zoomstart', function() { + * console.log('A zoomstart event occurred.'); + * }); */ | 'zoomstart' @@ -514,6 +796,13 @@ export type MapEvent = * @memberof Map * @instance * @property {MapMouseEvent | MapTouchEvent} data + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // repeatedly during a zoom transition. + * map.on('zoom', function() { + * console.log('A zoom event occurred.'); + * }); * @see [Update a choropleth layer by zoom level](https://www.mapbox.com/mapbox-gl-js/example/updating-choropleth/) */ | 'zoom' @@ -526,6 +815,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapMouseEvent | MapTouchEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // just after a zoom transition finishes. + * map.on('zoomend', function() { + * console.log('A zoomend event occurred.'); + * }); */ | 'zoomend' @@ -536,6 +833,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapMouseEvent | MapTouchEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // just before a "drag to rotate" interaction starts. + * map.on('rotatestart', function() { + * console.log('A rotatestart event occurred.'); + * }); */ | 'rotatestart' @@ -546,6 +851,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapMouseEvent | MapTouchEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // repeatedly during "drag to rotate" interaction. + * map.on('rotate', function() { + * console.log('A rotate event occurred.'); + * }); */ | 'rotate' @@ -556,6 +869,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapMouseEvent | MapTouchEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // just after a "drag to rotate" interaction ends. + * map.on('rotateend', function() { + * console.log('A rotateend event occurred.'); + * }); */ | 'rotateend' @@ -567,17 +888,34 @@ export type MapEvent = * @memberof Map * @instance * @property {MapEventData} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // just before a pitch (tilt) transition starts. + * map.on('pitchstart', function() { + * console.log('A pitchstart event occurred.'); + * }); */ | 'pitchstart' /** - * Fired whenever the map's pitch (tilt) changes as - * the result of either user interaction or methods such as {@link Map#flyTo}. + * Fired repeatedly during the map's pitch (tilt) animation between + * one state and another as the result of either user interaction + * or methods such as {@link Map#flyTo}. * * @event pitch * @memberof Map * @instance * @property {MapEventData} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // repeatedly during a pitch (tilt) transition. + * map.on('pitch', function() { + * console.log('A pitch event occurred.'); + * }); */ | 'pitch' @@ -589,6 +927,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapEventData} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // just after a pitch (tilt) transition ends. + * map.on('pitchend', function() { + * console.log('A pitchend event occurred.'); + * }); */ | 'pitchend' @@ -599,6 +945,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapBoxZoomEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // just before a "box zoom" interaction starts. + * map.on('boxzoomstart', function() { + * console.log('A boxzoomstart event occurred.'); + * }); */ | 'boxzoomstart' @@ -610,6 +964,14 @@ export type MapEvent = * @instance * @type {Object} * @property {MapBoxZoomEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // just after a "box zoom" interaction ends. + * map.on('boxzoomend', function() { + * console.log('A boxzoomend event occurred.'); + * }); */ | 'boxzoomend' @@ -621,6 +983,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapBoxZoomEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // the user cancels a "box zoom" interaction. + * map.on('boxzoomcancel', function() { + * console.log('A boxzoomcancel event occurred.'); + * }); */ | 'boxzoomcancel' @@ -630,6 +1000,14 @@ export type MapEvent = * @event resize * @memberof Map * @instance + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // immediately after the map has been resized. + * map.on('resize', function() { + * console.log('A resize event occurred.'); + * }); */ | 'resize' @@ -639,6 +1017,14 @@ export type MapEvent = * @event webglcontextlost * @memberof Map * @instance + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when the WebGL context is lost. + * map.on('webglcontextlost', function() { + * console.log('A webglcontextlost event occurred.'); + * }); */ | 'webglcontextlost' @@ -648,6 +1034,14 @@ export type MapEvent = * @event webglcontextrestored * @memberof Map * @instance + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when the WebGL context is restored. + * map.on('webglcontextrestored', function() { + * console.log('A webglcontextrestored event occurred.'); + * }); */ | 'webglcontextrestored' @@ -659,6 +1053,14 @@ export type MapEvent = * @memberof Map * @instance * @type {Object} + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when the map has finished loading. + * map.on('load', function() { + * console.log('A load event occurred.'); + * }); * @see [Draw GeoJSON points](https://www.mapbox.com/mapbox-gl-js/example/geojson-markers/) * @see [Add live realtime data](https://www.mapbox.com/mapbox-gl-js/example/live-geojson/) * @see [Animate a point](https://www.mapbox.com/mapbox-gl-js/example/animate-point-along-line/) @@ -676,6 +1078,14 @@ export type MapEvent = * @event render * @memberof Map * @instance + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // whenever the map is drawn to the screen. + * map.on('render', function() { + * console.log('A render event occurred.'); + * }); */ | 'render' @@ -690,6 +1100,14 @@ export type MapEvent = * @event idle * @memberof Map * @instance + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // just before the map enters an "idle" state. + * map.on('idle', function() { + * console.log('A idle event occurred.'); + * }); */ | 'idle' @@ -699,6 +1117,14 @@ export type MapEvent = * @event remove * @memberof Map * @instance + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // just after the map is removed. + * map.on('remove', function() { + * console.log('A remove event occurred.'); + * }); */ | 'remove' @@ -712,6 +1138,14 @@ export type MapEvent = * @memberof Map * @instance * @property {{error: {message: string}}} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when an error occurs. + * map.on('error', function() { + * console.log('A error event occurred.'); + * }); */ | 'error' @@ -723,6 +1157,15 @@ export type MapEvent = * @memberof Map * @instance * @property {MapDataEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when map data loads or changes. + * map.on('data', function() { + * console.log('A data event occurred.'); + * }); + * @see [Display HTML clusters with custom properties](https://docs.mapbox.com/mapbox-gl-js/example/cluster-html/) */ | 'data' @@ -734,6 +1177,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapDataEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when the map's style loads or changes. + * map.on('styledata', function() { + * console.log('A styledata event occurred.'); + * }); */ | 'styledata' @@ -745,6 +1196,14 @@ export type MapEvent = * @memberof Map * @instance * @property {MapDataEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when one of the map's sources loads or changes. + * map.on('sourcedata', function() { + * console.log('A sourcedata event occurred.'); + * }); */ | 'sourcedata' @@ -757,6 +1216,15 @@ export type MapEvent = * @memberof Map * @instance * @property {MapDataEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // when any map data begins loading + * // or changing asynchronously. + * map.on('dataloading', function() { + * console.log('A dataloading event occurred.'); + * }); */ | 'dataloading' @@ -769,6 +1237,15 @@ export type MapEvent = * @memberof Map * @instance * @property {MapDataEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // map's style begins loading or + * // changing asyncronously. + * map.on('styledataloading', function() { + * console.log('A styledataloading event occurred.'); + * }); */ | 'styledataloading' @@ -781,6 +1258,15 @@ export type MapEvent = * @memberof Map * @instance * @property {MapDataEvent} data + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // map's sources begin loading or + * // changing asyncronously. + * map.on('sourcedataloading', function() { + * console.log('A sourcedataloading event occurred.'); + * }); */ | 'sourcedataloading' @@ -793,7 +1279,14 @@ export type MapEvent = * @memberof Map * @instance * @property {string} id The id of the missing image. - * + * @example + * // Initialize the map + * var map = new mapboxgl.Map({ // map options }); + * // Set an event listener that fires + * // an icon or pattern is missing. + * map.on('styleimagemissing', function() { + * console.log('A styleimagemissing event occurred.'); + * }); * @see [Generate and add a missing icon to the map](https://mapbox.com/mapbox-gl-js/example/add-image-missing-generated/) */ | 'styleimagemissing' diff --git a/src/ui/handler/scroll_zoom.js b/src/ui/handler/scroll_zoom.js index a123a1e711e..a8fc61d109f 100644 --- a/src/ui/handler/scroll_zoom.js +++ b/src/ui/handler/scroll_zoom.js @@ -81,15 +81,21 @@ class ScrollZoomHandler { /** * Set the zoom rate of a trackpad * @param {number} [zoomRate=1/100] The rate used to scale trackpad movement to a zoom value. + * @example + * // Speed up trackpad zoom + * map.scrollZoom.setZoomRate(1/25); */ setZoomRate(zoomRate: number) { this._defaultZoomRate = zoomRate; } /** - * Set the zoom rate of a mouse wheel - * @param {number} [wheelZoomRate=1/450] The rate used to scale mouse wheel movement to a zoom value. - */ + * Set the zoom rate of a mouse wheel + * @param {number} [wheelZoomRate=1/450] The rate used to scale mouse wheel movement to a zoom value. + * @example + * // Slow down zoom of mouse wheel + * map.scrollZoom.setWheelZoomRate(1/600); + */ setWheelZoomRate(wheelZoomRate: number) { this._wheelZoomRate = wheelZoomRate; } diff --git a/src/ui/map.js b/src/ui/map.js index c1e5eee4dad..613bd549f47 100755 --- a/src/ui/map.js +++ b/src/ui/map.js @@ -925,33 +925,103 @@ class Map extends Camera { } /** - * Adds a listener for events of a specified type. - * - * @method - * @name on - * @memberof Map - * @instance - * @param {string} type The event type to add a listen for. - * @param {Function} listener The function to be called when the event is fired. - * The listener function is called with the data object passed to `fire`, - * extended with `target` and `type` properties. - * @returns {Map} `this` - */ - - /** - * Adds a listener for events of a specified type occurring on features in a specified style layer. - * - * @param {string} type The event type to listen for; one of `'mousedown'`, `'mouseup'`, `'click'`, `'dblclick'`, - * `'mousemove'`, `'mouseenter'`, `'mouseleave'`, `'mouseover'`, `'mouseout'`, `'contextmenu'`, `'touchstart'`, - * `'touchend'`, or `'touchcancel'`. `mouseenter` and `mouseover` events are triggered when the cursor enters - * a visible portion of the specified layer from outside that layer or outside the map canvas. `mouseleave` - * and `mouseout` events are triggered when the cursor leaves a visible portion of the specified layer, or leaves - * the map canvas. - * @param {string} layerId The ID of a style layer. Only events whose location is within a visible - * feature in this layer will trigger the listener. The event will have a `features` property containing - * an array of the matching features. + * Adds a listener for events of a specified type, optionally limited to features in a specified style layer. + * + * @param {string} type The event type to listen for. Events compatible with the optional `layerId` parameter are triggered + * when the cursor enters a visible portion of the specified layer from outside that layer or outside the map canvas. + * + * | Event | Compatible with `layerId` | + * |-----------------------------------------------------------|---------------------------| + * | [`mousedown`](#map.event:mousedown) | yes | + * | [`mouseup`](#map.event:mouseup) | yes | + * | [`mouseover`](#map.event:mouseover) | yes | + * | [`mouseout`](#map.event:mouseout) | yes | + * | [`mousemove`](#map.event:mousemove) | yes | + * | [`mouseenter`](#map.event:mouseenter) | yes (required) | + * | [`mouseleave`](#map.event:mouseleave) | yes (required) | + * | [`click`](#map.event:click) | yes | + * | [`dblclick`](#map.event:dblclick) | yes | + * | [`contextmenu`](#map.event:contextmenu) | yes | + * | [`touchstart`](#map.event:touchstart) | yes | + * | [`touchend`](#map.event:touchend) | yes | + * | [`touchcancel`](#map.event:touchcancel) | yes | + * | [`wheel`](#map.event:wheel) | | + * | [`resize`](#map.event:resize) | | + * | [`remove`](#map.event:remove) | | + * | [`touchmove`](#map.event:touchmove) | | + * | [`movestart`](#map.event:movestart) | | + * | [`move`](#map.event:move) | | + * | [`moveend`](#map.event:moveend) | | + * | [`dragstart`](#map.event:dragstart) | | + * | [`drag`](#map.event:drag) | | + * | [`dragend`](#map.event:dragend) | | + * | [`zoomstart`](#map.event:zoomstart) | | + * | [`zoom`](#map.event:zoom) | | + * | [`zoomend`](#map.event:zoomend) | | + * | [`rotatestart`](#map.event:rotatestart) | | + * | [`rotate`](#map.event:rotate) | | + * | [`rotateend`](#map.event:rotateend) | | + * | [`pitchstart`](#map.event:pitchstart) | | + * | [`pitch`](#map.event:pitch) | | + * | [`pitchend`](#map.event:pitchend) | | + * | [`boxzoomstart`](#map.event:boxzoomstart) | | + * | [`boxzoomend`](#map.event:boxzoomend) | | + * | [`boxzoomcancel`](#map.event:boxzoomcancel) | | + * | [`webglcontextlost`](#map.event:webglcontextlost) | | + * | [`webglcontextrestored`](#map.event:webglcontextrestored) | | + * | [`load`](#map.event:load) | | + * | [`render`](#map.event:render) | | + * | [`idle`](#map.event:idle) | | + * | [`error`](#map.event:error) | | + * | [`data`](#map.event:data) | | + * | [`styledata`](#map.event:styledata) | | + * | [`sourcedata`](#map.event:sourcedata) | | + * | [`dataloading`](#map.event:dataloading) | | + * | [`styledataloading`](#map.event:styledataloading) | | + * | [`sourcedataloading`](#map.event:sourcedataloading) | | + * | [`styleimagemissing`](#map.event:styleimagemissing) | | + * + * @param {string} layerId (optional) The ID of a style layer. Event will only be triggered if its location + * is within a visible feature in this layer. The event will have a `features` property containing + * an array of the matching features. If `layerId` is not supplied, the event will not have a `features` property. + * Please note that many event types are not compatible with the optional `layerId` parameter. * @param {Function} listener The function to be called when the event is fired. * @returns {Map} `this` + * @example + * // Set an event listener that will fire + * // when the map has finished loading + * map.on('load', function() { + * // Once the map has finished loading, + * // add a new layer + * 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 + * } + * }); + * }); + * @example + * // Set an event listener that will fire + * // when a feature on the countries layer of the map is clicked + * map.on('click', 'countries', function(e) { + * new mapboxgl.Popup() + * .setLngLat(e.lngLat) + * .setHTML(`Country name: ${e.features[0].properties.name}`) + * .addTo(map); + * }); + * @see [Display popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/) + * @see [Center the map on a clicked symbol](https://docs.mapbox.com/mapbox-gl-js/example/center-on-symbol/) + * @see [Create a hover effect](https://docs.mapbox.com/mapbox-gl-js/example/hover-styles/) + * @see [Create a draggable marker](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/) */ on(type: MapEvent, layerId: any, listener: any) { if (listener === undefined) { @@ -1326,9 +1396,9 @@ class Map extends Camera { } /** - * Returns the map's Mapbox style object, which can be used to recreate the map's style. + * Returns the map's Mapbox [style](https://docs.mapbox.com/help/glossary/style/) object, a JSON object which can be used to recreate the map's style. * - * @returns {Object} The map's style object. + * @returns {Object} The map's style JSON object. * * @example * var styleJson = map.getStyle(); @@ -1393,7 +1463,8 @@ class Map extends Camera { } /** - * Returns a Boolean indicating whether the source is loaded. + * Returns a Boolean indicating whether the source is loaded. Returns `true` if the source with + * the given ID in the map's style has no outstanding network requests, otherwise `false`. * * @param {string} id The ID of the source to be checked. * @returns {boolean} A Boolean indicating whether the source is loaded. @@ -1460,14 +1531,22 @@ class Map extends Camera { /** * Returns the source with the specified ID in the map's style. * + * This method is often used to update a source using the instance members for the relevant + * source type as defined in [Sources](#sources). + * For example, setting the `data` for a GeoJSON source or updating the `url` and `coordinates` + * of an image source. + * * @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. + * @returns {?Object} The style source with the specified ID or `undefined` if the ID + * corresponds to no existing sources. + * The shape of the object varies by source type. + * A list of options for each source type is available on the Mapbox Style Specification's + * [Sources](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/) page. * @example * 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/) + * @see [Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/) + * @see [Animate a point](https://docs.mapbox.com/mapbox-gl-js/example/animate-point-along-line/) + * @see [Add live realtime data](https://docs.mapbox.com/mapbox-gl-js/example/live-geojson/) */ getSource(id: string) { return this.style.getSource(id); @@ -1680,15 +1759,51 @@ class Map extends Camera { * 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://docs.mapbox.com/mapbox-gl-js/style-spec/#layers). + * @param {Object | CustomLayerInterface} layer The layer to add, conforming to either the Mapbox Style Specification's [layer definition](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers) or, less commonly, the [`CustomLayerInterface`](https://docs.mapbox.com/mapbox-gl-js/api/#customlayerinterface) specification. + * The Mapbox Style Specification's layer definition is appropriate for most layers. + * + * @param {string} layer.id A unique idenfier that you define. + * @param {string} layer.type The type of layer (for example `fill` or `symbol`). + * A list of layer types is available in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#type). + * + * (This can also be `custom`. For more information, see [`CustomLayerInterface`](https://docs.mapbox.com/mapbox-gl-js/api/#customlayerinterface).) + * @param {string | Object} [layer.source] The data source for the layer. + * Reference a source that has _already been defined_ using the source's unique id. + * Reference a _new source_ using a source object (as defined in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/)) directly. + * This is **required** for all `layer.type` options _except_ for `custom`. + * @param {string} [layer.sourceLayer] (optional) The name of the [source layer](https://docs.mapbox.com/help/glossary/source-layer/) within the specified `layer.source` to use for this style layer. + * This is only applicable for vector tile sources and is **required** when `layer.source` is of the type `vector`. + * @param {array} [layer.filter] (optional) An expression specifying conditions on source features. + * Only features that match the filter are displayed. + * The Mapbox Style Specification includes more information on the limitations of the [`filter`](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#filter) parameter + * and a complete list of available [expressions](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/). + * If no filter is provided, all features in the source (or source layer for vector tilesets) will be displayed. + * @param {Object} [layer.paint] (optional) Paint properties for the layer. + * Available paint properties vary by `layer.type`. + * A full list of paint properties for each layer type is available in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/). + * If no paint properties are specified, default values will be used. + * @param {Object} [layer.layout] (optional) Layout properties for the layer. + * Available layout properties vary by `layer.type`. + * A full list of layout properties for each layer type is available in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/). + * If no layout properties are specified, default values will be used. + * @param {number} [layer.maxzoom] (optional) The maximum zoom level for the layer. + * At zoom levels equal to or greater than the maxzoom, the layer will be hidden. + * The value can be any number between `0` and `24` (inclusive). + * If no maxzoom is provided, the layer will be visible at all zoom levels for which there are tiles available. + * @param {number} [layer.minzoom] (optional) The minimum zoom level for the layer. + * At zoom levels less than the minzoom, the layer will be hidden. + * The value can be any number between `0` and `24` (inclusive). + * If no minzoom is provided, the layer will be visible at all zoom levels for which there are tiles available. + * @param {Object} [layer.metadata] (optional) Arbitrary properties useful to track with the layer, but do not influence rendering. + * @param {string} [layer.renderingMode] This is only applicable for layers with the type `custom`. + * See [`CustomLayerInterface`](https://docs.mapbox.com/mapbox-gl-js/api/#customlayerinterface) for more information. * @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. + * If this argument is not specified, the layer will be appended to the end of the layers array. * * @returns {Map} `this` * * @example - * // Add a circle layer with a vector source. + * // Add a circle layer with a vector source * map.addLayer({ * id: 'points-of-interest', * source: { @@ -1705,9 +1820,44 @@ class Map extends Camera { * } * }); * - * @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/) + * @example + * // Define a source before using it to create a new layer + * map.addSource('state-data', { + * type: 'geojson', + * data: 'path/to/data.geojson' + * }); + * + * map.addLayer({ + * id: 'states', + * // References the GeoJSON source defined above + * // and does not require a `source-layer` + * source: 'state-data', + * type: 'symbol', + * layout: { + * // Set the label content to the + * // feature's `name` property + * text-field: ['get', 'name'] + * } + * }); + * + * @example + * // Add a new symbol layer before an existing layer + * map.addLayer({ + * id: 'states', + * // References a source that's already been defined + * source: 'state-data', + * type: 'symbol', + * layout: { + * // Set the label content to the + * // feature's `name` property + * text-field: ['get', 'name'] + * } + * // Add the layer before the existing `cities` layer + * }, 'cities'); + * + * @see [Create and style clusters](https://docs.mapbox.com/mapbox-gl-js/example/cluster/) + * @see [Add a vector tile source](https://docs.mapbox.com/mapbox-gl-js/example/vector-source/) + * @see [Add a WMS source](https://docs.mapbox.com/mapbox-gl-js/example/wms/) */ addLayer(layer: LayerSpecification | CustomLayerInterface, beforeId?: string) { this._lazyInitEmptyStyle(); @@ -1719,13 +1869,12 @@ class Map extends Camera { * Moves a layer to a different z-position. * * @param {string} id The ID of the layer to move. - * @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. + * @param {string} [beforeId] The ID of an existing layer to insert the new layer before. When viewing the map, the `id` layer will appear beneath the `beforeId` layer. If `beforeId` is omitted, the layer will be appended to the end of the layers array and appear above all other layers on the map. * @returns {Map} `this` * * @example - * // Move a layer with ID 'label' before the layer with ID 'waterways'. - * map.moveLayer('label', 'waterways'); + * // Move a layer with ID 'polygon' before the layer with ID 'country-label'. The `polygon` layer will appear beneath the `country-label` layer on the map. + * map.moveLayer('polygon', 'country-label'); */ moveLayer(id: string, beforeId?: string) { this.style.moveLayer(id, beforeId); @@ -1795,19 +1944,35 @@ class Map extends Camera { /** * Sets the filter for the specified style layer. * + * Filters control which features a style layer renders from its source. + * Any feature for which the filter expression evaluates to `true` will be + * rendered on the map. Those that are false will be hidden. + * + * Use `setFilter` to show a subset of your source data. + * + * To clear the filter, pass `null` or `undefined` as the second parameter. + * * @param {string} layerId The ID of the layer to which the filter will be applied. * @param {Array | null | undefined} filter The filter, conforming to the Mapbox Style Specification's * [filter definition](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#filter). If `null` or `undefined` is provided, the function removes any existing filter from the layer. * @param {Object} [options] Options object. * @param {boolean} [options.validate=true] Whether to check if the filter conforms to the Mapbox GL Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function. - * * @returns {Map} `this` + * * @example - * map.setFilter('my-layer', ['==', 'name', 'USA']); + * // display only features with the 'name' property 'USA' + * map.setFilter('my-layer', ['==', ['get', 'name'], 'USA']); + * @example + * // display only features with five or more 'available-spots' + * map.setFilter('bike-docks', ['>=', ['get', 'available-spots'], 5]); + * @example + * // remove the filter for the 'bike-docks' style layer + * map.setFilter('bike-docks', null); * * @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/) + * @see Tutorial: [Show changes over time](https://docs.mapbox.com/help/tutorials/show-changes-over-time/) */ setFilter(layerId: string, filter: ?FilterSpecification, options: StyleSetterOptions = {}) { this.style.setFilter(layerId, filter, options); @@ -1867,6 +2032,7 @@ class Map extends Camera { * @returns {Map} `this` * @example * map.setLayoutProperty('my-layer', 'visibility', 'none'); + * @see [Show and hide layers](https://docs.mapbox.com/mapbox-gl-js/example/toggle-layers/) */ setLayoutProperty(layerId: string, name: string, value: any, options: StyleSetterOptions = {}) { this.style.setLayoutProperty(layerId, name, value, options); @@ -1891,6 +2057,9 @@ class Map extends Camera { * @param {Object} [options] Options object. * @param {boolean} [options.validate=true] Whether to check if the filter conforms to the Mapbox GL Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function. * @returns {Map} `this` + * @example + * var layerVisibility = map.getLayoutProperty('my-layer', 'visibility'); + * @see [Show and hide layers](https://docs.mapbox.com/mapbox-gl-js/example/toggle-layers/) */ setLight(light: LightSpecification, options: StyleSetterOptions = {}) { this._lazyInitEmptyStyle(); @@ -1909,23 +2078,42 @@ class Map extends Camera { // eslint-disable-next-line jsdoc/require-returns /** - * Sets the state of a feature. The `state` object is merged in with the existing state of the feature. - * Features are identified by their `id` attribute, which must be an integer or a string that can be - * cast to an integer. + * Sets the `state` of a feature. + * A feature's `state` is a set of user-defined key-value pairs that are assigned to a feature at runtime. + * When using this method, the `state` object is merged with any existing key-value pairs in the feature's state. + * Features are identified by their `feature.id` attribute, which can be any number or string. + * + * This method can only be used with sources that have a `feature.id` attribute. The `feature.id` attribute can be defined in three ways: + * - For vector or GeoJSON sources, including an `id` attribute in the original data file. + * - For vector or GeoJSON sources, using the [`promoteId`](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/#vector-promoteId) option at the time the source is defined. + * - For GeoJSON sources, using the [`generateId`](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/#geojson-generateId) option to auto-assign an `id` based on the feature's index in the source data. If you change feature data using `map.getSource('some id').setData(..)`, you may need to re-apply state taking into account updated `id` values. + * + * _Note: You can use the [`feature-state` expression](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/#feature-state) to access the values in a feature's state object for the purposes of styling._ * * @param {Object} feature Feature identifier. Feature objects returned from * {@link Map#queryRenderedFeatures} or event handlers can be used as feature identifiers. * @param {string | number} feature.id Unique id of the feature. - * @param {string} feature.source The Id of the vector source or GeoJSON source for the feature. - * @param {string} [feature.sourceLayer] (optional) *For vector tile sources, the sourceLayer is - * required.* + * @param {string} feature.source The id of the vector or GeoJSON source for the feature. + * @param {string} [feature.sourceLayer] (optional) *For vector tile sources, `sourceLayer` is required.* * @param {Object} state A set of key-value pairs. The values should be valid JSON types. * - * This method requires the `feature.id` attribute on data sets. For GeoJSON sources without - * feature ids, set the `generateId` option in the `GeoJSONSourceSpecification` to auto-assign them. This - * option assigns ids based on a feature's index in the source data. If you change feature data using - * `map.getSource('some id').setData(..)`, you may need to re-apply state taking into account updated `id` values. + * @example + * // When the mouse moves over the `my-layer` layer, update + * // the feature state for the feature under the mouse + * map.on('mousemove', 'my-layer', function(e) { + * if (e.features.length > 0) { + * map.setFeatureState({ + * source: 'my-source', + * sourceLayer: 'my-source-layer', + * id: e.features[0].id, + * }, { + * hover: true + * }); + * } + * }); + * * @see [Create a hover effect](https://docs.mapbox.com/mapbox-gl-js/example/hover-styles/) + * @see Tutorial: [Create interactive hover effects with Mapbox GL JS](https://docs.mapbox.com/help/tutorials/create-interactive-hover-effects-with-mapbox-gl-js/) */ setFeatureState(feature: { source: string; sourceLayer?: string; id: string | number; }, state: Object) { this.style.setFeatureState(feature, state); @@ -1934,19 +2122,50 @@ class Map extends Camera { // eslint-disable-next-line jsdoc/require-returns /** - * Removes feature state, setting it back to the default behavior. If only - * source is specified, removes all states of that source. If - * target.id is also specified, removes all keys for that feature's state. - * If key is also specified, removes that key from that feature's state. - * Features are identified by their `id` attribute, which must be an integer or a string that can be - * cast to an integer. - * @param {Object} target Identifier of where to set state: can be a source, a feature, or a specific key of feature. + * Removes the `state` of a feature, setting it back to the default behavior. + * If only a `target.source` is specified, it will remove the state for all features from that source. + * If `target.id` is also specified, it will remove all keys for that feature's state. + * If `key` is also specified, it removes only that key from that feature's state. + * Features are identified by their `feature.id` attribute, which can be any number or string. + * + * @param {Object} target Identifier of where to remove state. It can be a source, a feature, or a specific key of feature. * Feature objects returned from {@link Map#queryRenderedFeatures} or event handlers can be used as feature identifiers. * @param {string | number} target.id (optional) Unique id of the feature. Optional if key is not specified. - * @param {string} target.source The Id of the vector source or GeoJSON source for the feature. - * @param {string} [target.sourceLayer] (optional) *For vector tile sources, the sourceLayer is - * required.* + * @param {string} target.source The id of the vector or GeoJSON source for the feature. + * @param {string} [target.sourceLayer] (optional) *For vector tile sources, `sourceLayer` is required.* * @param {string} key (optional) The key in the feature state to reset. + * + * @example + * // Reset the entire state object for all features + * // in the `my-source` source + * map.removeFeatureState({ + * source: 'my-source' + * }); + * + * @example + * // When the mouse leaves the `my-layer` layer, + * // reset the entire state object for the + * // feature under the mouse + * map.on('mouseleave', 'my-layer', function(e) { + * map.removeFeatureState({ + * source: 'my-source', + * sourceLayer: 'my-source-layer', + * id: e.features[0].id + * }); + * }); + * + * @example + * // When the mouse leaves the `my-layer` layer, + * // reset only the `hover` key-value pair in the + * // state for the feature under the mouse + * map.on('mouseleave', 'my-layer', function(e) { + * map.removeFeatureState({ + * source: 'my-source', + * sourceLayer: 'my-source-layer', + * id: e.features[0].id + * }, 'hover'); + * }); + * */ removeFeatureState(target: { source: string; sourceLayer?: string; id?: string | number; }, key?: string) { this.style.removeFeatureState(target, key); @@ -1954,18 +2173,33 @@ class Map extends Camera { } /** - * Gets the state of a feature. - * Features are identified by their `id` attribute, which must be an integer or a string that can be - * cast to an integer. + * Gets the `state` of a feature. + * A feature's `state` is a set of user-defined key-value pairs that are assigned to a feature at runtime. + * Features are identified by their `feature.id` attribute, which can be any number or string. + * + * _Note: To access the values in a feature's state object for the purposes of styling the feature, use the [`feature-state` expression](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/#feature-state)._ * * @param {Object} feature Feature identifier. Feature objects returned from * {@link Map#queryRenderedFeatures} or event handlers can be used as feature identifiers. * @param {string | number} feature.id Unique id of the feature. - * @param {string} feature.source The Id of the vector source or GeoJSON source for the feature. - * @param {string} [feature.sourceLayer] (optional) *For vector tile sources, the sourceLayer is - * required.* + * @param {string} feature.source The id of the vector or GeoJSON source for the feature. + * @param {string} [feature.sourceLayer] (optional) *For vector tile sources, `sourceLayer` is required.* + * + * @returns {Object} The state of the feature: a set of key-value pairs that was assigned to the feature at runtime. + * + * @example + * // When the mouse moves over the `my-layer` layer, + * // get the feature state for the feature under the mouse + * map.on('mousemove', 'my-layer', function(e) { + * if (e.features.length > 0) { + * map.getFeatureState({ + * source: 'my-source', + * sourceLayer: 'my-source-layer' + * id: e.features[0].id + * }); + * } + * }); * - * @returns {Object} The state of the feature. */ getFeatureState(feature: { source: string; sourceLayer?: string; id: string | number; }): any { return this.style.getFeatureState(feature); @@ -2344,6 +2578,10 @@ class Map extends Camera { * Trigger the rendering of a single frame. Use this method with custom layers to * repaint the map when the layer changes. Calling this multiple times before the * next frame is rendered will still result in only a single frame being rendered. + * @example + * map.triggerRepaint(); + * @see [Add a 3D model](https://docs.mapbox.com/mapbox-gl-js/example/add-3d-model/) + * @see [Add an animated icon to the map](https://docs.mapbox.com/mapbox-gl-js/example/add-image-animated/) */ triggerRepaint() { if (this.style && !this._frame) { @@ -2377,6 +2615,8 @@ class Map extends Camera { * @type {boolean} * @instance * @memberof Map + * @example + * map.showTileBoundaries = true; */ get showTileBoundaries(): boolean { return !!this._showTileBoundaries; } set showTileBoundaries(value: boolean) { @@ -2582,10 +2822,15 @@ function removeNode(node) { * `x` and `y` properties representing screen coordinates in pixels. * * @typedef {Object} Point + * @example + * var point = new mapboxgl.Point(-77, 38); */ /** * A {@link Point} or an array of two numbers representing `x` and `y` screen coordinates in pixels. * * @typedef {(Point | Array)} PointLike + * @example + * var p1 = new mapboxgl.Point(-77, 38); // a PointLike which is a Point + * var p2 = [-77, 38]; // a PointLike which is an array of two numbers */ diff --git a/src/ui/marker.js b/src/ui/marker.js index 55484adb013..0bb526743f4 100644 --- a/src/ui/marker.js +++ b/src/ui/marker.js @@ -216,9 +216,13 @@ export default class Marker extends Evented { } /** - * Attaches the marker to a map + * Attaches the `Marker` to a `Map` object. * @param {Map} map The Mapbox GL JS map to add the marker to. * @returns {Marker} `this` + * @example + * var marker = new mapboxgl.Marker() + * .setLngLat([30.5, 50.5]) + * .addTo(map); // add the marker to the map */ addTo(map: Map) { this.remove(); @@ -270,16 +274,30 @@ export default class Marker extends Evented { * the marker on screen. * * @returns {LngLat} A {@link LngLat} describing the marker's location. - */ + * @example + * // Store the marker's longitude and latitude coordinates in a variable + * var lngLat = marker.getLngLat(); + * // Print the marker's longitude and latitude values in the console + * console.log('Longitude: ' + lngLat.lng + ', Latitude: ' + lngLat.lat ) + * @see [Create a draggable Marker](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-marker/) + */ getLngLat() { return this._lngLat; } /** - * Set the marker's geographical position and move it. - * @param {LngLat} lnglat A {@link LngLat} describing where the marker should be located. - * @returns {Marker} `this` - */ + * Set the marker's geographical position and move it. + * @param {LngLat} lnglat A {@link LngLat} describing where the marker should be located. + * @returns {Marker} `this` + * @example + * // Create a new marker, set the longitude and latitude, and add it to the map + * new mapboxgl.Marker() + * .setLngLat([-65.017, -16.457]) + * .addTo(map); + * @see [Add custom icons with Markers](https://docs.mapbox.com/mapbox-gl-js/example/custom-marker-icons/) + * @see [Create a draggable Marker](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-marker/) + * @see [Add a marker using a place name](https://docs.mapbox.com/mapbox-gl-js/example/marker-from-geocode/) + */ setLngLat(lnglat: LngLatLike) { this._lngLat = LngLat.convert(lnglat); this._pos = null; @@ -297,10 +315,16 @@ export default class Marker extends Evented { } /** - * Binds a Popup to the Marker - * @param popup an instance of the `Popup` class. If undefined or null, any popup - * set on this `Marker` instance is unset + * Binds a {@link Popup} to the {@link Marker}. + * @param popup An instance of the {@link Popup} class. If undefined or null, any popup + * set on this {@link Marker} instance is unset. * @returns {Marker} `this` + * @example + * var marker = new mapboxgl.Marker() + * .setLngLat([0, 0]) + * .setPopup(new mapboxgl.Popup().setHTML("

Hello World!

")) // add popup + * .addTo(map); + * @see [Attach a popup to a marker instance](https://docs.mapbox.com/mapbox-gl-js/example/set-popup/) */ setPopup(popup: ?Popup) { if (this._popup) { @@ -364,16 +388,30 @@ export default class Marker extends Evented { } /** - * Returns the Popup instance that is bound to the Marker + * Returns the {@link Popup} instance that is bound to the {@link Marker}. * @returns {Popup} popup + * @example + * var marker = new mapboxgl.Marker() + * .setLngLat([0, 0]) + * .setPopup(new mapboxgl.Popup().setHTML("

Hello World!

")) + * .addTo(map); + * + * console.log(marker.getPopup()); // return the popup instance */ getPopup() { return this._popup; } /** - * Opens or closes the bound popup, depending on the current state + * Opens or closes the {@link Popup} instance that is bound to the {@link Marker}, depending on the current state of the {@link Popup}. * @returns {Marker} `this` + * @example + * var marker = new mapboxgl.Marker() + * .setLngLat([0, 0]) + * .setPopup(new mapboxgl.Popup().setHTML("

Hello World!

")) + * .addTo(map); + * + * marker.togglePopup(); // toggle popup open or closed */ togglePopup() { const popup = this._popup; diff --git a/src/ui/popup.js b/src/ui/popup.js index 8acb87e2192..2732eb82857 100644 --- a/src/ui/popup.js +++ b/src/ui/popup.js @@ -104,6 +104,15 @@ export default class Popup extends Evented { * * @param {Map} map The Mapbox GL JS map to add the popup to. * @returns {Popup} `this` + * @example + * new mapboxgl.Popup() + * .setLngLat([0, 0]) + * .setHTML("

Null Island

") + * .addTo(map); + * @see [Display a popup](https://docs.mapbox.com/mapbox-gl-js/example/popup/) + * @see [Display a popup on hover](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-hover/) + * @see [Display a popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/) + * @see [Show polygon information on click](https://docs.mapbox.com/mapbox-gl-js/example/polygon-popup-on-click/) */ addTo(map: Map) { if (this._map) this.remove(); @@ -139,6 +148,16 @@ export default class Popup extends Evented { * @instance * @type {Object} * @property {Popup} popup object that was opened + * + * @example + * // Create a popup + * var popup = new mapboxgl.Popup(); + * // Set an event listener that will fire + * // any time the popup is opened + * popup.on('open', function(){ + * console.log('popup was opened'); + * }); + * */ this.fire(new Event('open')); @@ -189,6 +208,16 @@ export default class Popup extends Evented { * @instance * @type {Object} * @property {Popup} popup object that was closed + * + * @example + * // Create a popup + * var popup = new mapboxgl.Popup(); + * // Set an event listener that will fire + * // any time the popup is closed + * popup.on('close', function(){ + * console.log('popup was closed'); + * }); + * */ this.fire(new Event('close')); @@ -235,8 +264,13 @@ export default class Popup extends Evented { } /** - * Tracks the popup anchor to the cursor position, on screens with a pointer device (will be hidden on touchscreens). Replaces the setLngLat behavior. - * For most use cases, `closeOnClick` and `closeButton` should also be set to `false` here. + * Tracks the popup anchor to the cursor position on screens with a pointer device (it will be hidden on touchscreens). Replaces the `setLngLat` behavior. + * For most use cases, set `closeOnClick` and `closeButton` to `false`. + * @example + * var popup = new mapboxgl.Popup({ closeOnClick: false, closeButton: false }) + * .setHTML("

Hello World!

") + * .trackPointer() + * .addTo(map); * @returns {Popup} `this` */ trackPointer() { @@ -259,6 +293,14 @@ export default class Popup extends Evented { /** * Returns the `Popup`'s HTML element. + * @example + * // Change the `Popup` element's font size + * var popup = new mapboxgl.Popup() + * .setLngLat([-96, 37.8]) + * .setHTML("

Hello World!

") + * .addTo(map); + * var popupElem = popup.getElement(); + * popupElem.style.fontSize = "25px"; * @returns {HTMLElement} element */ getElement() { @@ -293,6 +335,15 @@ export default class Popup extends Evented { * * @param html A string representing HTML content for the popup. * @returns {Popup} `this` + * @example + * var popup = new mapboxgl.Popup() + * .setLngLat(e.lngLat) + * .setHTML("

Hello World!

") + * .addTo(map); + * @see [Display a popup](https://docs.mapbox.com/mapbox-gl-js/example/popup/) + * @see [Display a popup on hover](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-hover/) + * @see [Display a popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/) + * @see [Attach a popup to a marker instance](https://docs.mapbox.com/mapbox-gl-js/example/set-popup/) */ setHTML(html: string) { const frag = window.document.createDocumentFragment(); diff --git a/src/util/ajax.js b/src/util/ajax.js index be730d0ed93..7c2d4445251 100644 --- a/src/util/ajax.js +++ b/src/util/ajax.js @@ -39,7 +39,23 @@ if (typeof Object.freeze == 'function') { * @typedef {Object} RequestParameters * @property {string} url The URL to be requested. * @property {Object} headers The headers to be sent with the request. + * @property {string} method Request method `'GET' | 'POST' | 'PUT'`. + * @property {string} body Request body. + * @property {string} type Response body type to be returned `'string' | 'json' | 'arrayBuffer'`. * @property {string} credentials `'same-origin'|'include'` Use 'include' to send cookies with cross-origin requests. + * @property {boolean} collectResourceTiming If true, Resource Timing API information will be collected for these transformed requests and returned in a resourceTiming property of relevant data events. + * @example + * // use transformRequest to modify requests that begin with `http://myHost` + * transformRequest: function(url, resourceType) { + * if (resourceType === 'Source' && url.indexOf('http://myHost') > -1) { + * return { + * url: url.replace('http', 'https'), + * headers: { 'my-custom-header': true }, + * credentials: 'include' // Include cookies for cross-origin requests + * } + * } + * } + * */ export type RequestParameters = { url: string, diff --git a/src/util/debug.js b/src/util/debug.js index 0255172726f..e26672e7472 100644 --- a/src/util/debug.js +++ b/src/util/debug.js @@ -5,6 +5,8 @@ import window from './window'; /** * This is a private namespace for utility functions that will get automatically stripped * out in production builds. + * + * @private */ export const Debug = { extend(dest: Object, ...sources: Array): Object {