Mapbox-gl-js: Clarify documentation for map.loaded(), map.isStyleLoaded()

[anandthakker]

mapbox-gl-js version: 0.45.0

Refs https://github.com/mapbox/mapbox-gl-js/issues/6707

The documentation for map.loaded() and map.isStyleLoaded() do not make it clear what the difference is between them.

    /**
     * Returns a Boolean indicating whether the map is fully loaded.
     *
     * Returns `false` if the style is not yet fully loaded,
     * or if there has been a change to the sources or style that
     * has not yet fully loaded.
     *
     * @returns {boolean} A Boolean indicating whether the map is fully loaded.
     */
    loaded()

    /**
     * Returns a Boolean indicating whether the map's style is fully loaded.
     *
     * @returns {boolean} A Boolean indicating whether the style is fully loaded.
     */
    isStyleLoaded()

It should be clear from reading the docs:

• What "fully loaded" means / what might cause it to be not true.
• Under what conditions map.loaded() !== map.isStyleLoaded()

[mike-marcacci]

I agree that some clarification would be helpful here. My initial assumption was that isStyleLoaded() would return false before the initial load and between a styledataloading event and subsequent styledata event, indicating that layers were not ready for queries. However, it appears to return false under a far wider range of conditions.

[stevage]

IMHO the important thing to include here is the implications of the current state: can you add sources, can you change paint or layout properties, can you manipulate the state otherwise.

[mourner]

Related: #5052, which stems from the same confusion over what map.loaded() means.

[hyperknot]

Is there a reference document about a map's lifecycle events? I'd like to know how are

• map.loaded()
• map.isStyleLoaded()
• map.on('load')
• map.on('idle')
• map.on('style.load')

connected on each other during the lifecycle of map.

Namely, is such a recursive setTimeout loop needed today?
https://github.com/mapbox/mapbox-gl-js/issues/2268#issuecomment-401979967

[ollydixon]

A quick example of how I do it, but an isLoaded call back would be great!

const goToLocation = (mapEvent: MapboxGl.Map) => {
        if (mapEvent.loaded()) {
            map.resize()
            map.flyTo({ center: [10.7522, 59.9139], animate: false, zoom: 13 })
        }
    }

    return (
        <Map
            style="mapbox://styles/mapbox/dark-v10"
            center={[10.7522, 59.9139]}
            onStyleLoad={(map) => goToLocation(map)}
        />
    );