Skip to content

Commit

Permalink
[WIP] Small fixes for GL JS API ref docs (#10643)
Browse files Browse the repository at this point in the history 
* quick formatting fixes for marker.js

* quick formatting fixes for geolocate_control.js

* quick formatting fixes for popup.js

* warnOnce

* but for real

Co-authored-by: Dom Brassey <dom.brassey@mapbox.com>
  • Loading branch information
@HeyStenson
HeyStenson and Dom Brassey authored Jul 8, 2021
1 parent 531690a commit 50cd794
Show file tree
Hide file tree
Showing 3 changed files with 56 additions and 42 deletions.
55 changes: 34 additions & 21 deletions src/ui/control/geolocate_control.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,21 +81,21 @@ let noTimeout = false;
* geolocation support is not available, the GeolocateControl will show
* as disabled.
*
* The zoom level applied will depend on the accuracy of the geolocation provided by the device.
* The [zoom level](https://docs.mapbox.com/help/glossary/zoom-level/) applied depends on the accuracy of the geolocation provided by the device.
*
* The GeolocateControl has two modes. If `trackUserLocation` is `false` (default) the control acts as a button, which when pressed will set the map's camera to target the user location. If the user moves, the map won't update. This is most suited for the desktop. If `trackUserLocation` is `true` the control acts as a toggle button that when active the user's location is actively monitored for changes. In this mode the GeolocateControl has three interaction states:
* * active - the map's camera automatically updates as the user's location changes, keeping the location dot in the center. Initial state and upon clicking the `GeolocateControl` button.
* * passive - the user's location dot automatically updates, but the map's camera does not. Occurs upon the user initiating a map movement.
* * disabled - occurs if Geolocation is not available, disabled or denied.
* * active - The map's camera automatically updates as the user's location changes, keeping the location dot in the center. This is the initial state, and the state upon clicking the `GeolocateControl` button.
* * passive - The user's location dot automatically updates, but the map's camera does not. Occurs upon the user initiating a map movement.
* * disabled - Occurs if geolocation is not available, disabled, or denied.
*
* These interaction states can't be controlled programmatically, rather they are set based on user interactions.
* These interaction states can't be controlled programmatically. Instead, they are set based on user interactions.
*
* @implements {IControl}
* @param {Object} [options]
* @param {Object} [options.positionOptions={enableHighAccuracy: false, timeout: 6000}] A Geolocation API [PositionOptions](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions) object.
* @param {Object} [options.fitBoundsOptions={maxZoom: 15}] A {@link Map#fitBounds} options object to use when the map is panned and zoomed to the user's location. The default is to use a `maxZoom` of 15 to limit how far the map will zoom in for very accurate locations.
* @param {Object} [options.trackUserLocation=false] If `true` the Geolocate Control becomes a toggle button and when active the map will receive updates to the user's location as it changes.
* @param {Object} [options.showAccuracyCircle=true] By default, if showUserLocation is `true`, a transparent circle will be drawn around the user location indicating the accuracy (95% confidence level) of the user's location. Set to `false` to disable. Always disabled when showUserLocation is `false`.
* @param {Object} [options.trackUserLocation=false] If `true` the GeolocateControl becomes a toggle button and when active the map will receive updates to the user's location as it changes.
* @param {Object} [options.showAccuracyCircle=true] By default, if `showUserLocation` is `true`, a transparent circle will be drawn around the user location indicating the accuracy (95% confidence level) of the user's location. Set to `false` to disable. Always disabled when `showUserLocation` is `false`.
* @param {Object} [options.showUserLocation=true] By default a dot will be shown on the map at the user's location. Set to `false` to disable.
* @param {Object} [options.showUserHeading=false] If `true` an arrow will be drawn next to the user location dot indicating the device's heading. This only has affect when `trackUserLocation` is `true`.
*
Expand Down Expand Up @@ -482,6 +482,19 @@ class GeolocateControl extends Evented {
*
* @param deviceOrientationEvent {DeviceOrientationEvent}
* @private
* @example
* // Initialize the GeolocateControl.
* 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();
* });
*/
_onDeviceOrientation(deviceOrientationEvent: DeviceOrientationEvent) {
// absolute is true if the orientation data is provided as the difference between the Earth's coordinate frame and the device's coordinate frame, or false if the orientation data is being provided in reference to some arbitrary, device-determined coordinate frame.
Expand Down Expand Up @@ -523,7 +536,7 @@ class GeolocateControl extends Evented {
// update watchState and do any outgoing state cleanup
switch (this._watchState) {
case 'OFF':
// turn on the Geolocate Control
// turn on the GeolocateControl
this._watchState = 'WAITING_ACTIVE';

this.fire(new Event('trackuserlocationstart'));
Expand All @@ -532,7 +545,7 @@ class GeolocateControl extends Evented {
case 'ACTIVE_LOCK':
case 'ACTIVE_ERROR':
case 'BACKGROUND_ERROR':
// turn off the Geolocate Control
// turn off the GeolocateControl
numberOfWatches--;
noTimeout = false;
this._watchState = 'OFF';
Expand Down Expand Up @@ -663,13 +676,13 @@ class GeolocateControl extends Evented {

export default GeolocateControl;

/* Geolocate Control Watch States
/* GeolocateControl Watch States
* This is the private state of the control.
*
* OFF
* off/inactive
* WAITING_ACTIVE
* Geolocate Control was clicked but still waiting for Geolocation API response with user location
* GeolocateControl was clicked but still waiting for Geolocation API response with user location
* ACTIVE_LOCK
* Showing the user location as a dot AND tracking the camera to be fixed to their location. If their location changes the map moves to follow.
* ACTIVE_ERROR
Expand All @@ -681,14 +694,14 @@ export default GeolocateControl;
*/

/**
* Fired on each Geolocation API position update which returned as success.
* Fired on each Geolocation API position update that returned as success.
*
* @event geolocate
* @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.
* // Initialize the GeolocateControl.
* var geolocate = new mapboxgl.GeolocateControl({
* positionOptions: {
* enableHighAccuracy: true
Expand All @@ -706,14 +719,14 @@ export default GeolocateControl;
*/

/**
* Fired on each Geolocation API position update which returned as an error.
* Fired on each Geolocation API position update that returned as an error.
*
* @event error
* @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.
* // Initialize the GeolocateControl.
* var geolocate = new mapboxgl.GeolocateControl({
* positionOptions: {
* enableHighAccuracy: true
Expand All @@ -731,14 +744,14 @@ export default GeolocateControl;
*/

/**
* Fired on each Geolocation API position update which returned as success but user position is out of map maxBounds.
* Fired on each Geolocation API position update that returned as success but user position is out of map `maxBounds`.
*
* @event outofmaxbounds
* @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.
* // Initialize the GeolocateControl.
* var geolocate = new mapboxgl.GeolocateControl({
* positionOptions: {
* enableHighAccuracy: true
Expand All @@ -756,13 +769,13 @@ export default GeolocateControl;
*/

/**
* Fired when the Geolocate Control changes to the active lock state, which happens either upon first obtaining a successful Geolocation API position for the user (a geolocate event will follow), or the user clicks the geolocate button when in the background state which uses the last known position to recenter the map and enter active lock state (no geolocate event will follow unless the users's location changes).
* Fired when the GeolocateControl changes to the active lock state, which happens either upon first obtaining a successful Geolocation API position for the user (a geolocate event will follow), or when the user clicks the geolocate button when in the background state, which uses the last known position to recenter the map and enter active lock state (no geolocate event will follow unless the users's location changes).
*
* @event trackuserlocationstart
* @memberof GeolocateControl
* @instance
* @example
* // Initialize the geolocate control.
* // Initialize the GeolocateControl.
* var geolocate = new mapboxgl.GeolocateControl({
* positionOptions: {
* enableHighAccuracy: true
Expand All @@ -780,13 +793,13 @@ export default GeolocateControl;
*/

/**
* Fired when the Geolocate Control changes to the background state, which happens when a user changes the camera during an active position lock. This only applies when trackUserLocation is true. In the background state, the dot on the map will update with location updates but the camera will not.
* Fired when the GeolocateControl changes to the background state, which happens when a user changes the camera during an active position lock. This only applies when trackUserLocation is true. In the background state, the dot on the map will update with location updates but the camera will not.
*
* @event trackuserlocationend
* @memberof GeolocateControl
* @instance
* @example
* // Initialize the geolocate control.
* // Initialize the GeolocateControl.
* var geolocate = new mapboxgl.GeolocateControl({
* positionOptions: {
* enableHighAccuracy: true
Expand Down
26 changes: 13 additions & 13 deletions src/ui/marker.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,10 +36,10 @@ export const TERRAIN_OCCLUDED_OPACITY = 0.2;
* @param {string} [options.anchor='center'] A string indicating the part of the Marker that should be positioned closest to the coordinate set via {@link Marker#setLngLat}.
* Options are `'center'`, `'top'`, `'bottom'`, `'left'`, `'right'`, `'top-left'`, `'top-right'`, `'bottom-left'`, and `'bottom-right'`.
* @param {PointLike} [options.offset] The offset in pixels as a {@link PointLike} object to apply relative to the element's center. Negatives indicate left and up.
* @param {string} [options.color='#3FB1CE'] The color to use for the default marker if options.element is not provided. The default is light blue.
* @param {number} [options.scale=1] The scale to use for the default marker if options.element is not provided. The default scale corresponds to a height of `41px` and a width of `27px`.
* @param {string} [options.color='#3FB1CE'] The color to use for the default marker if `options.element` is not provided. The default is light blue.
* @param {number} [options.scale=1] The scale to use for the default marker if `options.element` is not provided. The default scale corresponds to a height of `41px` and a width of `27px`.
* @param {boolean} [options.draggable=false] A boolean indicating whether or not a marker is able to be dragged to a new position on the map.
* @param {number} [options.clickTolerance=0] The max number of pixels a user can shift the mouse pointer during a click on the marker for it to be considered a valid click (as opposed to a marker drag). The default is to inherit map's clickTolerance.
* @param {number} [options.clickTolerance=0] The max number of pixels a user can shift the mouse pointer during a click on the marker for it to be considered a valid click (as opposed to a marker drag). The default is to inherit map's `clickTolerance`.
* @param {number} [options.rotation=0] The rotation angle of the marker in degrees, relative to its respective `rotationAlignment` setting. A positive value will rotate the marker clockwise.
* @param {string} [options.pitchAlignment='auto'] `map` aligns the `Marker` to the plane of the map. `viewport` aligns the `Marker` to the plane of the viewport. `auto` automatically matches the value of `rotationAlignment`.
* @param {string} [options.rotationAlignment='auto'] `map` aligns the `Marker`'s rotation relative to the map, maintaining a bearing as the map rotates. `viewport` aligns the `Marker`'s rotation relative to the viewport, agnostic to map rotations. `auto` is equivalent to `viewport`.
Expand Down Expand Up @@ -265,7 +265,7 @@ export default class Marker extends Evented {
}

/**
* Removes the marker from a map
* Removes the marker from a map.
* @example
* var marker = new mapboxgl.Marker().addTo(map);
* marker.remove();
Expand Down Expand Up @@ -558,7 +558,7 @@ export default class Marker extends Evented {
}

/**
* Sets the offset of the marker
* Sets the offset of the marker.
* @param {PointLike} offset The offset in pixels as a {@link PointLike} object to apply relative to the element's center. Negatives indicate left and up.
* @returns {Marker} `this`
*/
Expand Down Expand Up @@ -588,25 +588,25 @@ export default class Marker extends Evented {
this._state = 'active';

/**
* Fired when dragging starts
* Fired when dragging starts.
*
* @event dragstart
* @memberof Marker
* @instance
* @type {Object}
* @property {Marker} marker object that is being dragged
* @property {Marker} marker The object that is being dragged.
*/
this.fire(new Event('dragstart'));
}

/**
* Fired while dragging
* Fired while dragging.
*
* @event drag
* @memberof Marker
* @instance
* @type {Object}
* @property {Marker} marker object that is being dragged
* @property {Marker} marker The object that is being dragged.
*/
this.fire(new Event('drag'));
}
Expand All @@ -623,13 +623,13 @@ export default class Marker extends Evented {
// only fire dragend if it was preceded by at least one drag event
if (this._state === 'active') {
/**
* Fired when the marker is finished being dragged
* Fired when the marker is finished being dragged.
*
* @event dragend
* @memberof Marker
* @instance
* @type {Object}
* @property {Marker} marker object that was dragged
* @property {Marker} marker The object that was dragged.
*/
this.fire(new Event('dragend'));
}
Expand Down Expand Up @@ -660,7 +660,7 @@ export default class Marker extends Evented {
}

/**
* Sets the `draggable` property and functionality of the marker
* Sets the `draggable` property and functionality of the marker.
* @param {boolean} [shouldBeDraggable=false] Turns drag functionality on/off
* @returns {Marker} `this`
*/
Expand All @@ -683,7 +683,7 @@ export default class Marker extends Evented {
}

/**
* Returns true if the marker can be dragged
* Returns true if the marker can be dragged.
* @returns {boolean} True if the marker is draggable.
*/
isDraggable() {
Expand Down
17 changes: 9 additions & 8 deletions src/ui/popup.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,29 +51,30 @@ const focusQuerySelector = [
* @param {Object} [options]
* @param {boolean} [options.closeButton=true] If `true`, a close button will appear in the
* top right corner of the popup.
* @param {boolean} [options.closeOnClick=true] If `true`, the popup will closed when the
* @param {boolean} [options.closeOnClick=true] If `true`, the popup will close when the
* map is clicked.
* @param {boolean} [options.closeOnMove=false] If `true`, the popup will closed when the
* @param {boolean} [options.closeOnMove=false] If `true`, the popup will close when the
* map moves.
* @param {boolean} [options.focusAfterOpen=true] If `true`, the popup will try to focus the
* first focusable element inside the popup.
* @param {string} [options.anchor] - A string indicating the part of the Popup that should
* be positioned closest to the coordinate set via {@link Popup#setLngLat}.
* @param {string} [options.anchor] - A string indicating the part of the popup that should
* be positioned closest to the coordinate, set via {@link Popup#setLngLat}.
* Options are `'center'`, `'top'`, `'bottom'`, `'left'`, `'right'`, `'top-left'`,
* `'top-right'`, `'bottom-left'`, and `'bottom-right'`. If unset the anchor will be
* `'top-right'`, `'bottom-left'`, and `'bottom-right'`. If unset, the anchor will be
* dynamically set to ensure the popup falls within the map container with a preference
* for `'bottom'`.
* @param {number|PointLike|Object} [options.offset] -
* A pixel offset applied to the popup's location specified as:
* - a single number specifying a distance from the popup's location
* - a {@link PointLike} specifying a constant offset
* - an object of {@link Point}s specifing an offset for each anchor position
*
* Negative offsets indicate left and up.
* @param {string} [options.className] Space-separated CSS class names to add to popup container
* @param {string} [options.className] Space-separated CSS class names to add to popup container.
* @param {string} [options.maxWidth='240px'] -
* A string that sets the CSS property of the popup's maximum width, eg `'300px'`.
* A string that sets the CSS property of the popup's maximum width (for example, `'300px'`).
* To ensure the popup resizes to fit its content, set this property to `'none'`.
* Available values can be found here: https://developer.mozilla.org/en-US/docs/Web/CSS/max-width
* See the MDN documentation for the list of [available values](https://developer.mozilla.org/en-US/docs/Web/CSS/max-width).
* @example
* var markerHeight = 50, markerRadius = 10, linearOffset = 25;
* var popupOffsets = {
Expand Down

0 comments on commit 50cd794

Please sign in to comment.