Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[docs] Address user feedback for /api: setStyle, getStyle, isStyleLoaded #8807

Merged
merged 1 commit into from
Oct 28, 2019
Merged

[docs] Address user feedback for /api: setStyle, getStyle, isStyleLoaded #8807

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 19 additions & 3 deletions src/ui/map.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1032,9 +1032,14 @@ class Map extends Camera {
}

/**
* Updates the map's Mapbox style object with a new value. If a style already is set and options.diff is true,
* this compares the style against the map's current state and performs only the changes necessary to make
* the map style match the desired state.
* Updates the map's Mapbox style object with a new value.
*
* If a style is already set when this is used and options.diff is set to true, the map renderer will attempt to compare the given style
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be useful to add why it is valuable to enable to diff. If a style is not changing drastically, it enables a cross-faded change from the current style to the next and it is more performant - by reusing existing source and layer definitions and transitioning them to a future state - it saves on CPU cycles, and possibly network bandwidth.

* against the map's current state and perform only the changes necessary to make the map style match the desired state. Changes in sprites
* (images used for icons and patterns) and glyphs (fonts for label text) **cannot** be diffed. If the sprites or fonts used in the current
* style and the given style are different in any way, the map renderer will force a full update, removing the current style and building
* the given one from scratch.
*
*
* @param style A JSON object conforming to the schema described in the
* [Mapbox Style Specification](https://mapbox.com/mapbox-gl-style-spec/), or a URL to such JSON.
Expand All @@ -1047,6 +1052,10 @@ class Map extends Camera {
* Set to `false`, to enable font settings from the map's style for these glyph ranges.
* Forces a full update.
* @returns {Map} `this`
*
* @example
* map.setStyle("mapbox://styles/mapbox/streets-v11");
*
* @see [Change a map's style](https://www.mapbox.com/mapbox-gl-js/example/setstyle/)
*/
setStyle(style: StyleSpecification | string | null, options?: {diff?: boolean} & StyleOptions) {
Expand Down Expand Up @@ -1118,6 +1127,10 @@ class Map extends Camera {
* Returns the map's Mapbox style object, which can be used to recreate the map's style.
*
* @returns {Object} The map's style object.
*
* @example
* var styleJson = map.getStyle();
asheemmamoowala marked this conversation as resolved.
Show resolved Hide resolved
*
*/
getStyle() {
if (this.style) {
Expand All @@ -1129,6 +1142,9 @@ class Map extends Camera {
* Returns a Boolean indicating whether the map's style is fully loaded.
*
* @returns {boolean} A Boolean indicating whether the style is fully loaded.
*
* @example
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any chance I can add to the scope fo this PR to include improvements to address #6708 and #6707 as well?

* var styleLoadStatus = map.isStyleLoaded();
*/
isStyleLoaded() {
if (!this.style) return warnOnce('There is no style added to the map.');
Expand Down