Mapbox Maps Android/com.mapbox.maps.plugin.location/LocationPluginImpl

LocationPluginImpl

The Location Component provides location awareness to your mobile application. Enabling this component provides a contextual experience to your users by showing an icon representing the users current location. A few different modes are offered to provide the right context to your users at the correct time. RenderMode.NORMAL simply shows the users location on the map represented as a dot. RenderMode.COMPASS mode allows you to display an arrow icon (by default) that points in the direction the device is pointing in. RenderMode.GPS can be used in conjunction with our Navigation SDK to display a larger icon (customized with LocationComponentOptions.gpsDrawable) we call the user puck.

This component also offers the ability to set a map camera behavior for tracking the user location. These different CameraModes will track, stop tracking the location based on the mode set with LocationPluginImpl.setCameraMode.

** To get the component object use MapPluginProviderDelegate.getLocationPlugin and activate it with .activateLocationComponent or one of the overloads. Then, manage its visibility with .setLocationComponentEnabled. The component will not process location updates right after activation, but only after being enabled.

Using this component requires you to request permission beforehand manually or using PermissionsManager. Either ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION permissions can be requested for this component to work as expected.

This component offers a default, built-in LocationEngine with some of the activation methods. This engine will be obtained by LocationEngineProvider.getBestLocationEngine which defaults to the com.mapbox.android.core.location.MapboxFusedLocationEngineImpl. If you'd like to utilize Google Play Services for more precise location updates, simply add the Google Play Location Services dependency in your build script. This will make the default engine the com.mapbox.android.core.location.GoogleLocationEngineImpl instead. After a custom engine is passed to the component, or the built-in is initialized, the location updates are going to be requested with the LocationEngineRequest, either a default one, or the one passed during the activation. When using any engine, requesting/removing the location updates is going to be managed internally.

You can also push location updates to the component without any internal engine management. To achieve that, use .activateLocationComponent with false. No engine is going to be initialized and you can push location updates with .forceLocationUpdate.

For location puck animation purposes, like navigation, we recommend limiting the maximum zoom level of the map for the best user experience.

Location Component doesn't support state saving out-of-the-box.

class LocationPluginImpl : LocationPlugin

Constructors

LocationPluginImpl

Default empty constructor for LocationComponentPlugin.

fun LocationPluginImpl()

LocationPluginImpl

Internal use.

fun LocationPluginImpl(developerAnimationListeners: MutableList<OnDeveloperAnimationListener>)

Types

Companion

Static variables and methods.

object Companion

Functions

activateLocationComponent

This method initializes the component and needs to be called before any other operations are performed. Afterwards, you can manage component's visibility by .setLocationComponentEnabled.

fun activateLocationComponent(activationOptions: LocationComponentActivationOptions)

addOnCameraTrackingChangedListener

Adds a listener that gets invoked when camera tracking state changes.

fun addOnCameraTrackingChangedListener(listener: OnCameraTrackingChangedListener)

addOnIndicatorPositionChangedListener

Adds a listener that gets invoked when indicator position changes.

fun addOnIndicatorPositionChangedListener(listener: OnIndicatorPositionChangedListener)

addOnLocationClickListener

Adds a listener that gets invoked when the user clicks the displayed location.

If there are registered location click listeners and the location is clicked, only OnLocationClickListener.onLocationComponentClick is going to be delivered, com.mapbox.mapboxsdk.maps.MapboxMap.OnMapClickListener.onMapClick is going to be consumed and not pushed to the listeners registered after the component's activation.

fun addOnLocationClickListener(listener: OnLocationClickListener)

addOnLocationLongClickListener

Adds a listener that gets invoked when the user long clicks the displayed location.

If there are registered location long click listeners and the location is long clicked, only OnLocationLongClickListener.onLocationComponentLongClick is going to be delivered, com.mapbox.mapboxsdk.maps.MapboxMap.OnMapLongClickListener.onMapLongClick is going to be consumed and not pushed to the listeners registered after the component's activation.

fun addOnLocationLongClickListener(listener: OnLocationLongClickListener)

addOnLocationStaleListener

Adds the passed listener that gets invoked when user updates have stopped long enough for the last update to be considered stale.

This timeout is set by LocationComponentOptions.staleStateTimeout.

fun addOnLocationStaleListener(listener: OnLocationStaleListener)

addOnRenderModeChangedListener

Adds a listener that gets invoked when render mode changes.

fun addOnRenderModeChangedListener(listener: OnRenderModeChangedListener)

applyStyle

Apply a new component style with location component options.

fun applyStyle(options: LocationComponentOptions)

Apply a new component style with a style resource.

fun applyStyle(context: Context, @StyleRes() styleRes: Int)

cancelPaddingWhileTrackingAnimation

Cancels animation started by .paddingWhileTracking.

fun cancelPaddingWhileTrackingAnimation()

cancelPitchWhileTrackingAnimation

Cancels animation started by .tiltWhileTracking.

fun cancelPitchWhileTrackingAnimation()

cancelZoomWhileTrackingAnimation

Cancels animation started by .zoomWhileTracking.

fun cancelZoomWhileTrackingAnimation()

cleanup

open override fun cleanup()

equals

open operator override fun equals(other: Any?): Boolean

forceLocationUpdate

Use to either force a location update or to manually control when the user location gets updated.

fun forceLocationUpdate(location: Location?)

fun forceLocationUpdate(locationUpdate: LocationUpdate)

getCompassEngine

Returns the compass engine used to provide compass heading values.

fun getCompassEngine(): CompassEngine?

getLocationEngine

Returns the current LocationEngine being used for updating the user location.

fun getLocationEngine(): LocationEngine?

getLocationEngineRequest

Get the location request that's going to be used when requesting location updates.

fun getLocationEngineRequest(): LocationEngineRequest

hashCode

open override fun hashCode(): Int

initialize

open override fun initialize()

onCameraMove

Called whenever camera position changes.

open override fun onCameraMove(lat: Double, lon: Double, zoom: Double, pitch: Double, bearing: Double, padding: Array<Double>?, anchor: Pair<Double, Double>?)

onDelegateProvider

Provides all map delegate instances.

open override fun onDelegateProvider(delegateProvider: MapDelegateProvider)

onDestroy

Internal use.

fun onDestroy()

onFinishLoadingStyle

Internal use.

fun onFinishLoadingStyle()

onStart

Called whenever activity's/fragment's lifecycle is entering a "started" state.

open override fun onStart()

onStartLoadingMap

Internal use.

fun onStartLoadingMap()

onStop

Called whenever activity's/fragment's lifecycle is entering a "stopped" state.

open override fun onStop()

onStyleChanged

Called when a new Style is loaded.

open override fun onStyleChanged(styleDelegate: StyleManagerInterface)

paddingWhileTracking

Sets the padding. This API can only be used in pair with camera modes other than CameraMode.NONE. If you are not using any of CameraMode modes, use one of MapboxMap.moveCamera, MapboxMap.easeCamera or MapboxMap.animateCamera instead.

If the camera is transitioning when the padding change is requested, the call is going to be ignored. Use CameraTransitionListener to chain the animations, or provide the padding as a camera change argument.

fun paddingWhileTracking(padding: DoubleArray)

fun paddingWhileTracking(padding: DoubleArray, animationDuration: Long)

fun paddingWhileTracking(padding: DoubleArray, animationDuration: Long, callback: CancelableCallback?)

pitchWhileTracking

Pitches the camera. This API can only be used in pair with camera modes other than CameraMode.NONE. If you are not using any of CameraMode modes, use one of MapboxMap.moveCamera, MapboxMap.easeCamera or MapboxMap.animateCamera instead.

If the camera is transitioning when the pitch change is requested, the call is going to be ignored. Use CameraTransitionListener to chain the animations, or provide the pitch as a camera change argument.

fun pitchWhileTracking(pitch: Double)

Tilts the camera. This API can only be used in pair with camera modes other than CameraMode.NONE. If you are not using any of CameraMode modes, use one of MapboxMap.moveCamera, MapboxMap.easeCamera or MapboxMap.animateCamera instead.

fun pitchWhileTracking(pitch: Double, animationDuration: Long)

fun pitchWhileTracking(pitch: Double, animationDuration: Long, callback: CancelableCallback?)

removeOnCameraTrackingChangedListener

Removes a listener that gets invoked when camera tracking state changes.

fun removeOnCameraTrackingChangedListener(listener: OnCameraTrackingChangedListener)

removeOnIndicatorPositionChangedListener

Removes a listener that gets invoked when indicator position changes.

fun removeOnIndicatorPositionChangedListener(listener: OnIndicatorPositionChangedListener)

removeOnLocationClickListener

Removes the passed listener from the current list of location click listeners.

fun removeOnLocationClickListener(listener: OnLocationClickListener)

removeOnLocationLongClickListener

Removes the passed listener from the current list of location long click listeners.

fun removeOnLocationLongClickListener(listener: OnLocationLongClickListener)

removeOnLocationStaleListener

Removes the passed listener from the current list of stale listeners.

fun removeOnLocationStaleListener(listener: OnLocationStaleListener)

removeRenderModeChangedListener

Removes a listener that gets invoked when render mode changes.

fun removeRenderModeChangedListener(listener: OnRenderModeChangedListener)

setCameraMode

Sets the camera mode, which determines how the map camera will track the rendered location.

When camera is transitioning to a new mode, it will reject inputs like .zoomWhileTracking or .tiltWhileTracking. Use OnLocationCameraTransitionListener to listen for the transition state.

CameraMode.NONE: No camera tracking
CameraMode.NONE_COMPASS: Camera does not track location, but does track compass bearing
CameraMode.NONE_GPS: Camera does not track location, but does track GPS bearing
CameraMode.TRACKING: Camera tracks the user location
CameraMode.TRACKING_COMPASS: Camera tracks the user location, with bearing provided by a compass
CameraMode.TRACKING_GPS: Camera tracks the user location, with normalized bearing
CameraMode.TRACKING_GPS_NORTH: Camera tracks the user location, with bearing always set to north

fun setCameraMode(cameraMode: CameraMode, transitionListener: OnLocationCameraTransitionListener?)

Sets the camera mode, which determines how the map camera will track the rendered location.

When camera is transitioning to a new mode, it will reject inputs like .zoomWhileTracking or .tiltWhileTracking. Use OnLocationCameraTransitionListener to listen for the transition state.

Set values of zoom, bearing and pitch that the camera will transition to. If null is passed to any of those, current value will be used for that parameter instead. If the camera is already tracking, provided values are ignored.

CameraMode.NONE: No camera tracking
CameraMode.NONE_COMPASS: Camera does not track location, but does track compass bearing
CameraMode.NONE_GPS: Camera does not track location, but does track GPS bearing
CameraMode.TRACKING: Camera tracks the user location
CameraMode.TRACKING_COMPASS: Camera tracks the user location, with bearing provided by a compass
CameraMode.TRACKING_GPS: Camera tracks the user location, with normalized bearing
CameraMode.TRACKING_GPS_NORTH: Camera tracks the user location, with bearing always set to north

fun setCameraMode(cameraMode: CameraMode, transitionDuration: Long, zoom: Double?, bearing: Double?, pitch: Double?, transitionListener: OnLocationCameraTransitionListener?)

setCompassEngine

Sets the compass engine used to provide compass heading values.

fun setCompassEngine(compassEngine: CompassEngine?)

setLocationEngine

Set the location engine to update the current user location.

If null is passed in, all updates will have to occur through the LocationPluginImpl.forceLocationUpdate method.

fun setLocationEngine(locationEngine: LocationEngine?)

setLocationEngineRequest

Set the location request that's going to be used when requesting location updates.

fun setLocationEngineRequest(locationEngineRequest: LocationEngineRequest)

setMaxAnimationFps

Set max FPS at which location animators can output updates. The throttling will only impact the location puck and camera tracking smooth animations.

Setting this will not impact any other animations schedule with MapboxMap, gesture animations or .zoomWhileTracking/.tiltWhileTracking.

Use this setting to limit animation rate of the location puck on higher zoom levels to decrease the stress on the device's CPU which can directly improve battery life, without sacrificing UX.

Example usage:

<pre> `mapboxMap.addOnCameraIdleListener(new MapboxMap.OnCameraIdleListener() { { @}Override public void onCameraIdle() { double zoom = mapboxMap.getCameraPosition().zoom; int maxAnimationFps; if (zoom < 5) { maxAnimationFps = 3; } else if (zoom < 10) { maxAnimationFps = 5; } else if (zoom < 15) { maxAnimationFps = 7; } else if (zoom < 18) { maxAnimationFps = 15; } else { maxAnimationFps = Integer.MAX_VALUE; } locationComponent.setMaxAnimationFps(maxAnimationFps); } }); </pre>

If you're looking for a way to throttle the FPS of the whole map, including other animations and gestures, see MapView.setMaximumFps.

fun setMaxAnimationFps(maxAnimationFps: Int)

toString

open override fun toString(): String

zoomWhileTracking

Zooms to the desired zoom level. This API can only be used in pair with camera modes other than CameraMode.NONE. If you are not using any of CameraMode modes, use one of MapboxMap.moveCamera, MapboxMap.easeCamera or MapboxMap.animateCamera instead.

If the camera is transitioning when the zoom change is requested, the call is going to be ignored. Use CameraTransitionListener to chain the animations, or provide the zoom as a camera change argument.

fun zoomWhileTracking(zoomLevel: Double)

fun zoomWhileTracking(zoomLevel: Double, animationDuration: Long)

Zooms to the desired zoom level. This API can only be used in pair with camera modes other than CameraMode.NONE. If you are not using any of CameraMode modes, use one of MapTransformDelegate.moveBy, MapTransformDelegate.easeTo or ) instead.

fun zoomWhileTracking(zoomLevel: Double, animationDuration: Long, callback: CancelableCallback?)

Properties

cameraMode

The camera mode determines how the map camera will track the rendered location.

When camera is transitioning to a new mode, it will reject inputs like .zoomWhileTracking or .tiltWhileTracking. Use OnLocationCameraTransitionListener to listen for the transition state.

CameraMode.NONE: No camera tracking
CameraMode.NONE_COMPASS: Camera does not track location, but does track compass bearing
CameraMode.NONE_GPS: Camera does not track location, but does track GPS bearing
CameraMode.TRACKING: Camera tracks the user location
CameraMode.TRACKING_COMPASS: Camera tracks the user location, with bearing provided by a compass
CameraMode.TRACKING_GPS: Camera tracks the user location, with normalized bearing
CameraMode.TRACKING_GPS_NORTH: Camera tracks the user location, with bearing always set to north