MapboxMap

The general class to interact with in the Mapbox Maps SDK for Android. It exposes the entry point for all methods related to the Map object. You cannot instantiate MapboxMap object directly, rather, you must obtain one from the getMapboxMap() method MapView that you have added to your application.

Note: Similar to a View object, a MapboxMap should only be read and modified from the main thread.

Types

Companion
Link copied to clipboard

A convenience object to access MapboxMap's static utilities.

object Companion

Functions

addOnCameraChangeListener
Link copied to clipboard

Add a listener that's going to be invoked whenever map camera changes.

open override fun addOnCameraChangeListener(onCameraChangeListener: OnCameraChangeListener)
addOnMapIdleListener
Link copied to clipboard

Add a listener that's going to be invoked whenever map has entered the idle state.

The Map is in the idle state when there are no ongoing transitions and the Map has rendered all available tiles.

open override fun addOnMapIdleListener(onMapIdleListener: OnMapIdleListener)
addOnMapLoadedListener
Link copied to clipboard

Add a listener that's going to be invoked whenever the Map's style has been fully loaded, and the Map has rendered all visible tiles.

open override fun addOnMapLoadedListener(onMapLoadedListener: OnMapLoadedListener)
addOnMapLoadErrorListener
Link copied to clipboard

Add a listener that's going to be invoked whenever there's a map load error.

open override fun addOnMapLoadErrorListener(onMapLoadErrorListener: OnMapLoadErrorListener)
addOnRenderFrameFinishedListener
Link copied to clipboard

Add a listener that's going to be invoked whenever the Map finished rendering a frame.

The render-mode value tells whether the Map has all data ("full") required to render the visible viewport. The needs-repaint value provides information about ongoing transitions that trigger Map repaint. The placement-changed value tells if the symbol placement has been changed in the visible viewport.

open override fun addOnRenderFrameFinishedListener(onRenderFrameFinishedListener: OnRenderFrameFinishedListener)
addOnRenderFrameStartedListener
Link copied to clipboard

Add a listener that's going to be invoked whenever the Map started rendering a frame.

open override fun addOnRenderFrameStartedListener(onRenderFrameStartedListener: OnRenderFrameStartedListener)
addOnSourceAddedListener
Link copied to clipboard

Add a listener that's going to be invoked whenever a source has been added with StyleManager#addStyleSource runtime API.

open override fun addOnSourceAddedListener(onSourceAddedListener: OnSourceAddedListener)
addOnSourceDataLoadedListener
Link copied to clipboard

Add a listener that's going to be invoked whenever the source data has been loaded.

open override fun addOnSourceDataLoadedListener(onSourceDataLoadedListener: OnSourceDataLoadedListener)
addOnSourceRemovedListener
Link copied to clipboard

Add a listener that's going to be invoked whenever a source has been removed with StyleManager#removeStyleSource runtime API.

open override fun addOnSourceRemovedListener(onSourceRemovedListener: OnSourceRemovedListener)
addOnStyleDataLoadedListener
Link copied to clipboard

Add a listener that's going to be invoked whenever the requested style data been loaded. The 'type' property defines what kind of style data has been loaded.

This event may be useful when application needs to modify style layers or sources and add or remove sources before style is fully loaded.

open override fun addOnStyleDataLoadedListener(onStyleDataLoadedListener: OnStyleDataLoadedListener)
addOnStyleImageMissingListener
Link copied to clipboard

Add a listener that's going to be invoked whenever a style has a missing image.

This event is emitted when the Map renders visible tiles and one of the required images is missing in the sprite sheet.

open override fun addOnStyleImageMissingListener(onStyleImageMissingListener: OnStyleImageMissingListener)
addOnStyleImageUnusedListener
Link copied to clipboard

Add a listener that's going to be invoked whenever an image added to the Style is no longer needed and can be removed using StyleManager#removeStyleImage method.

open override fun addOnStyleImageUnusedListener(onStyleImageUnusedListener: OnStyleImageUnusedListener)
addOnStyleLoadedListener
Link copied to clipboard

Add a listener that's going to be invoked whenever the requested style has been fully loaded, including the style specified sprite and sources.

open override fun addOnStyleLoadedListener(onStyleLoadedListener: OnStyleLoadedListener)
cameraAnimationsPlugin
Link copied to clipboard

Call extension function on CameraAnimationsPlugin. In most cases should not be called directly.

open override fun cameraAnimationsPlugin(function: CameraAnimationsPlugin.() -> Any?): Any?
cameraForCoordinateBounds
Link copied to clipboard

Convert to a camera options from a given LatLngBounds, padding, bearing and pitch values.

In order for this method to produce correct results MapView must be already measured and inflated to have correct width and height values. Calling this method in Activity.onCreate will lead to incorrect results.

open override fun cameraForCoordinateBounds(bounds: CoordinateBounds, padding: EdgeInsets, bearing: Double?, pitch: Double?): CameraOptions
cameraForCoordinates
Link copied to clipboard

Convenience method that returns the camera options object for given arguments

In order for this method to produce correct results MapView must be already measured and inflated to have correct width and height values. Calling this method in Activity.onCreate will lead to incorrect results.

Returns the camera options object for given arguments with zoom adjusted to fit \p coordinates into \p box, so that coordinates on the left, top and right of \p camera.center fit into \p box. Returns the provided camera options object unchanged upon error.

open override fun cameraForCoordinates(coordinates: List<Point>, camera: CameraOptions, box: ScreenBox): CameraOptions

Convert to a camera options from a given list of points, padding, bearing and pitch values.

In order for this method to produce correct results MapView must be already measured and inflated to have correct width and height values. Calling this method in Activity.onCreate will lead to incorrect results.

open override fun cameraForCoordinates(coordinates: List<Point>, padding: EdgeInsets, bearing: Double?, pitch: Double?): CameraOptions
cameraForGeometry
Link copied to clipboard

Convert to a camera options from a given geometry, padding, bearing and pitch values.

In order for this method to produce correct results MapView must be already measured and inflated to have correct width and height values. Calling this method in Activity.onCreate will lead to incorrect results.

open override fun cameraForGeometry(geometry: Geometry, padding: EdgeInsets, bearing: Double?, pitch: Double?): CameraOptions
clearData
Link copied to clipboard

Clears temporary map data.

Clears temporary map data from the data path defined in the given resource options. Useful to reduce the disk usage or in case the disk cache contains invalid data.

Note that calling this API will affect all maps that use the same data path and does not affect persistent map data like offline style packages.

fun clearData(callback: AsyncOperationResultCallback)
coordinateBoundsForCamera
Link copied to clipboard

Convert to a LatLngBounds from a given camera options.

In order for this method to produce correct results MapView must be already measured and inflated to have correct width and height values. Calling this method in Activity.onCreate will lead to incorrect results.

open override fun coordinateBoundsForCamera(camera: CameraOptions): CoordinateBounds
coordinateBoundsZoomForCamera
Link copied to clipboard

Returns the coordinate bounds and zoom for a given camera.

In order for this method to produce correct results MapView must be already measured and inflated to have correct width and height values. Calling this method in Activity.onCreate will lead to incorrect results.

Note that if the given camera shows the antimeridian, the returned wrapped bounds might not represent the minimum bounding box.

See also {@link #coordinateBoundsZoomForCameraUnwrapped}

open override fun coordinateBoundsZoomForCamera(camera: CameraOptions): CoordinateBoundsZoom
coordinateBoundsZoomForCameraUnwrapped
Link copied to clipboard

Returns the unwrapped coordinate bounds and zoom for a given camera.

In order for this method to produce correct results MapView must be already measured and inflated to have correct width and height values. Calling this method in Activity.onCreate will lead to incorrect results.

This method is particularly useful, if the camera shows the antimeridian.

open override fun coordinateBoundsZoomForCameraUnwrapped(camera: CameraOptions): CoordinateBoundsZoom
coordinateForPixel
Link copied to clipboard

Calculate a geographical coordinate(i.e., longitude-latitude pair) that corresponds to a screen coordinate.

The screen coordinate is in MapOptions.size platform pixels relative to the top left of the map (not of the whole screen).

Map must be fully loaded for getting an altitude-compliant result if using 3D terrain.

open override fun coordinateForPixel(pixel: ScreenCoordinate): Point
coordinateForProjectedMeters
Link copied to clipboard

Calculate a longitude-latitude pair for a Spherical Mercator projected meters.

open override fun coordinateForProjectedMeters(projectedMeters: ProjectedMeters): Point
coordinatesForPixels
Link copied to clipboard

Calculate geographical coordinates(i.e., longitude-latitude pair) that corresponds to screen coordinates.

The screen coordinates are in MapOptions.size platform pixels relative to the top left of the map (not of the whole screen).

Map must be fully loaded for getting an altitude-compliant result if using 3D terrain.

open override fun coordinatesForPixels(pixels: List<ScreenCoordinate>): List<Point>
dragEnd
Link copied to clipboard

Ends the ongoing drag gesture. This function should be called always after the user has ended a drag gesture initiated by dragStart.

open override fun dragEnd()
dragStart
Link copied to clipboard

Prepares the drag gesture to use the provided screen coordinate as a pivot point. This function should be called each time when user starts a dragging action (e.g. by clicking on the map). The following dragging will be relative to the pivot.

open override fun dragStart(point: ScreenCoordinate)
equals
Link copied to clipboard
open operator override fun equals(other: Any?): Boolean
executeOnRenderThread
Link copied to clipboard

In some cases querying source / render features is expected to be a blocking operation e.g. performing this action on map click. In this case in order to avoid deadlock on main thread querying could be performed on render thread and in that case querying result will be also delivered on render thread not leading to the main thread deadlock. Example:

fun onMapClick() { executeOnRenderThread { queryRenderedFeatures(pixel, options) { // result callback called, do needed actions lock.notify() } } lock.wait() return false }

open override fun executeOnRenderThread(runnable: Runnable)
gesturesPlugin
Link copied to clipboard

Call extension function on GesturesPlugin. In most cases should not be called directly.

open override fun gesturesPlugin(function: GesturesPlugin.() -> Any?): Any?
getBounds
Link copied to clipboard

Get the map bounds options.

open override fun getBounds(): CameraBounds
getDebug
Link copied to clipboard

Get debug options

fun getDebug(): List<MapDebugOptions>
getDragCameraOptions
Link copied to clipboard

Calculates target point where camera should move after drag. The method should be called after dragStart and before dragEnd.

open override fun getDragCameraOptions(fromPoint: ScreenCoordinate, toPoint: ScreenCoordinate): CameraOptions
getElevation
Link copied to clipboard

Get elevation for given coordinate. Value is available only for the visible region on the screen, if terrain (DEM) tile is available.

fun getElevation(coordinate: Point): Double?
getFeatureState
Link copied to clipboard

Get the state map of a feature within a style source.

Note that updates to feature state are asynchronous, so changes made by other methods might not be immediately visible.

fun getFeatureState(sourceId: String, sourceLayerId: String?, featureId: String, callback: QueryFeatureStateCallback)
getFreeCameraOptions
Link copied to clipboard

Get the map's current free camera options. After mutation, it should be set back to the map.

open override fun getFreeCameraOptions(): FreeCameraOptions
getMapOptions
Link copied to clipboard

Get map options.

open override fun getMapOptions(): MapOptions
getMapProjection
Link copied to clipboard

Get current map projection for Mapbox map.

Please note that even if MapboxMap is configured to use MapProjection.Globe starting from MapProjection.TRANSITION_ZOOM_LEVEL and above this method will return MapProjection.Mercator.

open override fun getMapProjection(): MapProjection
getMetersPerPixelAtLatitude
Link copied to clipboard

Calculate distance spanned by one pixel at the specified latitude at current zoom level.

open override fun getMetersPerPixelAtLatitude(latitude: Double): Double

Calculate distance spanned by one pixel at the specified latitude and zoom level.

open override fun getMetersPerPixelAtLatitude(latitude: Double, zoom: Double): Double
getPrefetchZoomDelta
Link copied to clipboard

Get the prefetch zoom delta

fun getPrefetchZoomDelta(): Byte
getRenderCacheOptions
Link copied to clipboard

Get the current RenderCacheOptions.

The size of the render cache is in megabytes. Returned value is zero if the feature is disabled.

fun getRenderCacheOptions(): RenderCacheOptions
getResourceOptions
Link copied to clipboard

Get the ResourceOptions the map was initialized with.

fun getResourceOptions(): ResourceOptions
getSize
Link copied to clipboard

Gets the size of the map.

open override fun getSize(): Size
getStyle
Link copied to clipboard

Get the Style of the map synchronously, will return null is style is not loaded yet.

fun getStyle(): Style?

Get the Style of the map asynchronously.

fun getStyle(onStyleLoaded: Style.OnStyleLoaded)
hashCode
Link copied to clipboard
open override fun hashCode(): Int
isFullyLoaded
Link copied to clipboard

Returns if the style has been fully loaded.

open override fun isFullyLoaded(): Boolean
isGestureInProgress
Link copied to clipboard

Returns if a gesture is in progress.

open override fun isGestureInProgress(): Boolean
isUserAnimationInProgress
Link copied to clipboard

Returns if user animation is currently in progress.

open override fun isUserAnimationInProgress(): Boolean
loadStyle
Link copied to clipboard

Load the style from Style Extension.

fun loadStyle(styleExtension: StyleContract.StyleExtension)
fun loadStyle(styleExtension: StyleContract.StyleExtension, onStyleLoaded: Style.OnStyleLoaded)
fun loadStyle(styleExtension: StyleContract.StyleExtension, onStyleLoaded: Style.OnStyleLoaded?, onMapLoadErrorListener: OnMapLoadErrorListener?)
loadStyleJson
Link copied to clipboard

Load style JSON.

fun loadStyleJson(styleJson: String)
fun loadStyleJson(styleJson: String, onStyleLoaded: Style.OnStyleLoaded)

Load style JSON

fun loadStyleJson(styleJson: String, onStyleLoaded: Style.OnStyleLoaded?, onMapLoadErrorListener: OnMapLoadErrorListener?)
loadStyleUri
Link copied to clipboard

Will load a new map style asynchronous from the specified URI.

fun loadStyleUri(styleUri: String)
fun loadStyleUri(styleUri: String, onStyleLoaded: Style.OnStyleLoaded)

Will load a new map style asynchronous from the specified URI.

URI can take the following forms:

  • Constants: load one of the bundled styles in Style.

  • mapbox://styles/<user>/<style>: loads the style from a Mapbox account. user is your username. style is the ID of your custom style created in Mapbox Studio.

  • http://... or https://...: loads the style over the Internet from any web server.

  • asset://...: loads the style from the APK assets directory. This is used to load a style bundled with your app.

  • file://...: loads the style from a file path. This is used to load a style from disk.

fun loadStyleUri(styleUri: String, onStyleLoaded: Style.OnStyleLoaded?, onMapLoadErrorListener: OnMapLoadErrorListener?)
pixelForCoordinate
Link copied to clipboard

Calculate a screen coordinate that corresponds to a geographical coordinate (i.e., longitude-latitude pair).

The screen coordinate is in MapOptions.size platform pixels relative to the top left of the map (not of the whole screen).

Map must be fully loaded for getting an altitude-compliant result if using 3D terrain.

open override fun pixelForCoordinate(coordinate: Point): ScreenCoordinate
pixelsForCoordinates
Link copied to clipboard

Calculate screen coordinates that corresponds to geographical coordinates (i.e., longitude-latitude pair).

The screen coordinates are in MapOptions.size platform pixels relative to the top left of the map (not of the whole screen).

Map must be fully loaded for getting an altitude-compliant result if using 3D terrain.

open override fun pixelsForCoordinates(coordinates: List<Point>): List<ScreenCoordinate>
project
Link copied to clipboard

Calculate a point on the map in Mercator Projection for a given coordinate at the specified zoom scale.

open override fun project(point: Point, zoomScale: Double): MercatorCoordinate
projectedMetersForCoordinate
Link copied to clipboard

Calculate Spherical Mercator ProjectedMeters coordinates.

open override fun projectedMetersForCoordinate(point: Point): ProjectedMeters
queryFeatureExtensions
Link copied to clipboard

Queries for feature extension values in a GeoJSON source.

fun queryFeatureExtensions(sourceIdentifier: String, feature: Feature, extension: String, extensionField: String, args: HashMap<String, Value>?, callback: QueryFeatureExtensionCallback)
queryRenderedFeatures
Link copied to clipboard

Queries the map for rendered features.

open override fun queryRenderedFeatures(box: ScreenBox, options: RenderedQueryOptions, callback: QueryFeaturesCallback)
open override fun queryRenderedFeatures(pixel: ScreenCoordinate, options: RenderedQueryOptions, callback: QueryFeaturesCallback)
open override fun queryRenderedFeatures(shape: List<ScreenCoordinate?>, options: RenderedQueryOptions, callback: QueryFeaturesCallback)
querySourceFeatures
Link copied to clipboard

Queries the map for source features.

open override fun querySourceFeatures(sourceId: String, options: SourceQueryOptions, callback: QueryFeaturesCallback)
reduceMemoryUse
Link copied to clipboard

Reduce memory use. Useful to call when the application gets paused or sent to background.

fun reduceMemoryUse()
removeFeatureState
Link copied to clipboard

Remove entries from a feature state map.

Remove a specified entry or all entries from a feature's state map, depending on the value of stateKey.

Note that updates to feature state are asynchronous, so changes made by this method migth not be immediately visible using getStateFeature().

fun removeFeatureState(sourceId: String, sourceLayerId: String?, featureId: String, stateKey: String?)
removeOnCameraChangeListener
Link copied to clipboard

Remove the camera change listener.

open override fun removeOnCameraChangeListener(onCameraChangeListener: OnCameraChangeListener)
removeOnMapIdleListener
Link copied to clipboard

Remove the map idle listener.

open override fun removeOnMapIdleListener(onMapIdleListener: OnMapIdleListener)
removeOnMapLoadedListener
Link copied to clipboard

Remove the map loaded listener.

open override fun removeOnMapLoadedListener(onMapLoadedListener: OnMapLoadedListener)
removeOnMapLoadErrorListener
Link copied to clipboard

Remove the map error listener.

open override fun removeOnMapLoadErrorListener(onMapLoadErrorListener: OnMapLoadErrorListener)
removeOnRenderFrameFinishedListener
Link copied to clipboard

Remove the render frame finished listener.

open override fun removeOnRenderFrameFinishedListener(onRenderFrameFinishedListener: OnRenderFrameFinishedListener)
removeOnRenderFrameStartedListener
Link copied to clipboard

Remove the render frame started listener.

open override fun removeOnRenderFrameStartedListener(onRenderFrameStartedListener: OnRenderFrameStartedListener)
removeOnSourceAddedListener
Link copied to clipboard

Remove the source added listener.

open override fun removeOnSourceAddedListener(onSourceAddedListener: OnSourceAddedListener)
removeOnSourceDataLoadedListener
Link copied to clipboard

Remove the source data loaded listener.

open override fun removeOnSourceDataLoadedListener(onSourceDataLoadedListener: OnSourceDataLoadedListener)
removeOnSourceRemovedListener
Link copied to clipboard

Remove the source removed listener.

open override fun removeOnSourceRemovedListener(onSourceRemovedListener: OnSourceRemovedListener)
removeOnStyleDataLoadedListener
Link copied to clipboard

Remove the style data loaded listener

open override fun removeOnStyleDataLoadedListener(onStyleDataLoadedListener: OnStyleDataLoadedListener)
removeOnStyleImageMissingListener
Link copied to clipboard

Remove the style image missing listener.

open override fun removeOnStyleImageMissingListener(onStyleImageMissingListener: OnStyleImageMissingListener)
removeOnStyleImageUnusedListener
Link copied to clipboard

Remove the style image unused listener.

open override fun removeOnStyleImageUnusedListener(onStyleImageUnusedListener: OnStyleImageUnusedListener)
removeOnStyleLoadedListener
Link copied to clipboard

Remove the style loaded listener.

open override fun removeOnStyleLoadedListener(onStyleLoadedListener: OnStyleLoadedListener)
setBounds
Link copied to clipboard

Set the map bounds.

open override fun setBounds(options: CameraBoundsOptions): Expected<String, None>
setCamera
Link copied to clipboard

Changes the map view by any combination of center, zoom, bearing, and pitch, without an animated transition. The map will retain its current values for any details not passed via the camera options argument. It is not guaranteed that the provided CameraOptions will be set, the map may apply constraints resulting in a different CameraState.

open override fun setCamera(cameraOptions: CameraOptions)

Sets the map view with the free camera options.

FreeCameraOptions provides more direct access to the underlying camera entity. For backwards compatibility the state set using this API must be representable with CameraOptions as well. Parameters are clamped to a valid range or discarded as invalid if the conversion to the pitch and bearing presentation is ambiguous. For example orientation can be invalid if it leads to the camera being upside down or the quaternion has zero length.

open override fun setCamera(freeCameraOptions: FreeCameraOptions)
setConstrainMode
Link copied to clipboard

Set the map constrain mode

open override fun setConstrainMode(constrainMode: ConstrainMode)
setDebug
Link copied to clipboard

Set debug options

fun setDebug(debugOptions: List<MapDebugOptions>, enabled: Boolean)
setFeatureState
Link copied to clipboard

Update the state map of a feature within a style source.

Update entries in the state map of a given feature within a style source. Only entries listed in the \p state map will be updated. An entry in the feature state map that is not listed in \p state will retain its previous value.

Note that updates to feature state are asynchronous, so changes made by this method migth not be immediately visible using getStateFeature().

fun setFeatureState(sourceId: String, sourceLayerId: String?, featureId: String, state: Value)
setGestureInProgress
Link copied to clipboard

Notify map about gesture being in progress.

open override fun setGestureInProgress(inProgress: Boolean)
setMapProjection
Link copied to clipboard

Set map projection for Mapbox map.

open override fun setMapProjection(mapProjection: MapProjection)
setNorthOrientation
Link copied to clipboard

Set the map north orientation

open override fun setNorthOrientation(northOrientation: NorthOrientation)
setPrefetchZoomDelta
Link copied to clipboard

Set the prefetch zoom delta

fun setPrefetchZoomDelta(delta: Byte)
setRenderCacheOptions
Link copied to clipboard

Enables or disables the experimental render cache feature.

Render cache is an experimental feature aiming to reduce resource usage of map rendering by caching intermediate rendering results of tiles into specific cache textures for reuse between frames. Performance benefit of the cache depends on the style as not all layers are cacheable due to e.g. viewport aligned features. Render cache always prefers quality over performance.

If RenderCacheOptions.size is not specified explicitly when using RenderCacheOptions.Builder - render cache will be disabled. If RenderCacheOptions.size is less than zero - IllegalArgumentException will be thrown.

fun setRenderCacheOptions(options: RenderCacheOptions)
setUserAnimationInProgress
Link copied to clipboard

Tells the map rendering engine that the animation is currently performed by the user (e.g. with a setCamera() calls series). It adjusts the engine for the animation use case. In particular, it brings more stability to symbol placement and rendering.

open override fun setUserAnimationInProgress(inProgress: Boolean)
setViewportMode
Link copied to clipboard

Set the map viewport mode

open override fun setViewportMode(viewportMode: ViewportMode)
subscribe
Link copied to clipboard

Subscribes an Observer to a provided list of event types. Observable will hold a strong reference to an \sa Observer instance, therefore, in order to stop receiving notifications, caller must call unsubscribe with an \sa Observer instance used for an initial subscription.

open override fun subscribe(observer: Observer, events: List<String>)
toString
Link copied to clipboard
open override fun toString(): String
triggerRepaint
Link copied to clipboard

Triggers a repaint of the map.

fun triggerRepaint()
unproject
Link copied to clipboard

Calculate a coordinate for a given point on the map in Mercator Projection.

open override fun unproject(coordinate: MercatorCoordinate, zoomScale: Double): Point
unsubscribe
Link copied to clipboard

Unsubscribes an Observer from all events.

open override fun unsubscribe(observer: Observer)

Unsubscribes an Observer from a provided list of event types.

open override fun unsubscribe(observer: Observer, events: List<String>)

Properties

cameraState
Link copied to clipboard

Represents current camera state.

open override val cameraState: CameraState