com.mapbox.mapboxsdk.location

Class LocationComponent

java.lang.Object

com.mapbox.mapboxsdk.location.LocationComponent

public final class LocationComponent
extends java.lang.Object

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 setCameraMode(int).

To get the component object use MapboxMap.getLocationComponent() and activate it with activateLocationComponent(Context, Style) or one of the overloads. Then, manage its visibility with setLocationComponentEnabled(boolean). 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(Context, boolean) 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(Context, Style, boolean) with false. No engine is going to be initialized and you can push location updates with forceLocationUpdate(Location).

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.

Constructor Summary

Constructors

Constructor and Description
LocationComponent(MapboxMap mapboxMap, Transform transform, java.util.List<MapboxMap.OnDeveloperAnimationListener> developerAnimationListeners) Internal use.

Method Summary

Modifier and Type	Method and Description
void	activateLocationComponent(android.content.Context context, Style style) Deprecated. use LocationComponentActivationOptions.Builder instead
void	activateLocationComponent(android.content.Context context, Style style, boolean useDefaultLocationEngine) Deprecated. use LocationComponentActivationOptions.Builder instead
void	activateLocationComponent(android.content.Context context, Style style, boolean useDefaultLocationEngine, LocationEngineRequest locationEngineRequest) Deprecated. use LocationComponentActivationOptions.Builder instead
void	activateLocationComponent(android.content.Context context, Style style, boolean useDefaultLocationEngine, LocationEngineRequest locationEngineRequest, LocationComponentOptions options) Deprecated. use LocationComponentActivationOptions.Builder instead
void	activateLocationComponent(android.content.Context context, Style style, int styleRes) Deprecated. use LocationComponentActivationOptions.Builder instead
void	activateLocationComponent(android.content.Context context, Style style, LocationComponentOptions options) Deprecated. use LocationComponentActivationOptions.Builder instead
void	activateLocationComponent(android.content.Context context, Style style, LocationEngine locationEngine) Deprecated. use LocationComponentActivationOptions.Builder instead
void	activateLocationComponent(android.content.Context context, Style style, LocationEngine locationEngine, int styleRes) Deprecated. use LocationComponentActivationOptions.Builder instead
void	activateLocationComponent(android.content.Context context, Style style, LocationEngine locationEngine, LocationComponentOptions options) Deprecated. use LocationComponentActivationOptions.Builder instead
void	activateLocationComponent(android.content.Context context, Style style, LocationEngine locationEngine, LocationEngineRequest locationEngineRequest) Deprecated. use LocationComponentActivationOptions.Builder instead
void	activateLocationComponent(android.content.Context context, Style style, LocationEngine locationEngine, LocationEngineRequest locationEngineRequest, int styleRes) Deprecated. use LocationComponentActivationOptions.Builder instead
void	activateLocationComponent(android.content.Context context, Style style, LocationEngine locationEngine, LocationEngineRequest locationEngineRequest, LocationComponentOptions options) Deprecated. use LocationComponentActivationOptions.Builder instead
void	activateLocationComponent(LocationComponentActivationOptions activationOptions) This method initializes the component and needs to be called before any other operations are performed.
void	addOnCameraTrackingChangedListener(OnCameraTrackingChangedListener listener) Adds a listener that gets invoked when camera tracking state changes.
void	addOnIndicatorPositionChangedListener(OnIndicatorPositionChangedListener listener) Adds a listener that gets invoked when indicator position changes.
void	addOnLocationClickListener(OnLocationClickListener listener) Adds a listener that gets invoked when the user clicks the displayed location.
void	addOnLocationLongClickListener(OnLocationLongClickListener listener) Adds a listener that gets invoked when the user long clicks the displayed location.
void	addOnLocationStaleListener(OnLocationStaleListener listener) Adds the passed listener that gets invoked when user updates have stopped long enough for the last update to be considered stale.
void	addOnRenderModeChangedListener(OnRenderModeChangedListener listener) Adds a listener that gets invoked when render mode changes.
void	applyStyle(android.content.Context context, int styleRes) Apply a new component style with a style resource.
void	applyStyle(LocationComponentOptions options) Apply a new component style with location component options.
void	cancelPaddingWhileTrackingAnimation() Cancels animation started by paddingWhileTracking(double[], long, MapboxMap.CancelableCallback).
void	cancelTiltWhileTrackingAnimation() Cancels animation started by tiltWhileTracking(double, long, MapboxMap.CancelableCallback).
void	cancelZoomWhileTrackingAnimation() Cancels animation started by zoomWhileTracking(double, long, MapboxMap.CancelableCallback).
void	forceLocationUpdate(java.util.List<android.location.Location> locations, boolean lookAheadUpdate) Use to either force a location update or to manually control when the user location gets updated.
void	forceLocationUpdate(android.location.Location location) Use to either force a location update or to manually control when the user location gets updated.
int	getCameraMode() Provides the current camera mode being used to track the location or compass updates.
CompassEngine	getCompassEngine() Returns the compass engine used to provide compass heading values.
android.location.Location	getLastKnownLocation() Get the last know location of the location component.
LocationComponentOptions	getLocationComponentOptions() Returns the current location options being used.
LocationEngine	getLocationEngine() Returns the current LocationEngine being used for updating the user location.
LocationEngineRequest	getLocationEngineRequest() Get the location request that's going to be used when requesting location updates.
int	getRenderMode() Provides the current render mode being used to show the location and/or compass updates on the map.
boolean	isLocationComponentActivated() Returns whether the location component is activated.
boolean	isLocationComponentEnabled() Returns whether the plugin is enabled, meaning that location can be displayed and camera modes can be used.
void	onDestroy() Internal use.
void	onFinishLoadingStyle() Internal use.
void	onStart() Internal use.
void	onStartLoadingMap() Internal use.
void	onStop() Internal use.
void	paddingWhileTracking(double[] padding) Sets the padding.
void	paddingWhileTracking(double[] padding, long animationDuration) Sets the padding.
void	paddingWhileTracking(double[] padding, long animationDuration, MapboxMap.CancelableCallback callback) Sets the padding.
void	removeOnCameraTrackingChangedListener(OnCameraTrackingChangedListener listener) Removes a listener that gets invoked when camera tracking state changes.
void	removeOnIndicatorPositionChangedListener(OnIndicatorPositionChangedListener listener) Removes a listener that gets invoked when indicator position changes.
void	removeOnLocationClickListener(OnLocationClickListener listener) Removes the passed listener from the current list of location click listeners.
void	removeOnLocationLongClickListener(OnLocationLongClickListener listener) Removes the passed listener from the current list of location long click listeners.
void	removeOnLocationStaleListener(OnLocationStaleListener listener) Removes the passed listener from the current list of stale listeners.
void	removeRenderModeChangedListener(OnRenderModeChangedListener listener) Removes a listener that gets invoked when render mode changes.
void	setCameraMode(int cameraMode) Sets the camera mode, which determines how the map camera will track the rendered location.
void	setCameraMode(int cameraMode, long transitionDuration, java.lang.Double zoom, java.lang.Double bearing, java.lang.Double tilt, OnLocationCameraTransitionListener transitionListener) Sets the camera mode, which determines how the map camera will track the rendered location.
void	setCameraMode(int cameraMode, OnLocationCameraTransitionListener transitionListener) Sets the camera mode, which determines how the map camera will track the rendered location.
void	setCompassEngine(CompassEngine compassEngine) Sets the compass engine used to provide compass heading values.
void	setLocationComponentEnabled(boolean isEnabled) Manage component's visibility after activation.
void	setLocationEngine(LocationEngine locationEngine) Set the location engine to update the current user location.
void	setLocationEngineRequest(LocationEngineRequest locationEngineRequest) Set the location request that's going to be used when requesting location updates.
void	setMaxAnimationFps(int maxAnimationFps) Set max FPS at which location animators can output updates.
void	setRenderMode(int renderMode) Sets the render mode, which determines how the location updates will be rendered on the map.
void	tiltWhileTracking(double tilt) Tilts the camera.
void	tiltWhileTracking(double tilt, long animationDuration) Tilts the camera.
void	tiltWhileTracking(double tilt, long animationDuration, MapboxMap.CancelableCallback callback) Tilts the camera.
void	zoomWhileTracking(double zoomLevel) Zooms to the desired zoom level.
void	zoomWhileTracking(double zoomLevel, long animationDuration) Zooms to the desired zoom level.
void	zoomWhileTracking(double zoomLevel, long animationDuration, MapboxMap.CancelableCallback callback) Zooms to the desired zoom level.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LocationComponent

public LocationComponent(MapboxMap mapboxMap,
                         Transform transform,
                         java.util.List<MapboxMap.OnDeveloperAnimationListener> developerAnimationListeners)

Internal use.

To get the component object use MapboxMap.getLocationComponent().

Method Detail

activateLocationComponent

@Deprecated
public void activateLocationComponent(android.content.Context context,
                                                  Style style)

Deprecated. use LocationComponentActivationOptions.Builder instead

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(boolean).

Note: This method will initialize and use an internal LocationEngine when enabled.

Parameters:

context - the context

style - the proxy object for current map style. More info at Style

activateLocationComponent

@Deprecated
public void activateLocationComponent(android.content.Context context,
                                                  Style style,
                                                  boolean useDefaultLocationEngine)

Deprecated. use LocationComponentActivationOptions.Builder instead

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(boolean).

Parameters:

context - the context

style - the proxy object for current map style. More info at Style

useDefaultLocationEngine - true if you want to initialize and use the built-in location engine or false if there should be no location engine initialized

activateLocationComponent

@Deprecated
public void activateLocationComponent(android.content.Context context,
                                                  Style style,
                                                  boolean useDefaultLocationEngine,
                                                  LocationEngineRequest locationEngineRequest)

Deprecated. use LocationComponentActivationOptions.Builder instead

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(boolean).

Parameters:

context - the context

style - the proxy object for current map style. More info at Style

useDefaultLocationEngine - true if you want to initialize and use the built-in location engine or false if there should be no location engine initialized

locationEngineRequest - the location request

activateLocationComponent

@Deprecated
public void activateLocationComponent(android.content.Context context,
                                                  Style style,
                                                  boolean useDefaultLocationEngine,
                                                  LocationEngineRequest locationEngineRequest,
                                                  LocationComponentOptions options)

Deprecated. use LocationComponentActivationOptions.Builder instead

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(boolean).

Parameters:

context - the context

style - the proxy object for current map style. More info at Style

useDefaultLocationEngine - true if you want to initialize and use the built-in location engine or false if there should be no location engine initialized

locationEngineRequest - the location request

options - the options

activateLocationComponent

@Deprecated
public void activateLocationComponent(android.content.Context context,
                                                  Style style,
                                                  int styleRes)

Deprecated. use LocationComponentActivationOptions.Builder instead

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(boolean).

Note: This method will initialize and use an internal LocationEngine when enabled.

Parameters:

context - the context

style - the proxy object for current map style. More info at Style

styleRes - the LocationComponent style res

activateLocationComponent

@Deprecated
public void activateLocationComponent(android.content.Context context,
                                                  Style style,
                                                  LocationComponentOptions options)

Deprecated. use LocationComponentActivationOptions.Builder instead

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(boolean).

Note: This method will initialize and use an internal LocationEngine when enabled.

Parameters:

context - the context

style - the proxy object for current map style. More info at Style

options - the options

activateLocationComponent

@Deprecated
public void activateLocationComponent(android.content.Context context,
                                                  Style style,
                                                  LocationEngine locationEngine,
                                                  int styleRes)

Deprecated. use LocationComponentActivationOptions.Builder instead

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(boolean).

Parameters:

context - the context

style - the proxy object for current map style. More info at Style

locationEngine - the engine, or null if you'd like to only force location updates

styleRes - the LocationComponent style res

activateLocationComponent

@Deprecated
public void activateLocationComponent(android.content.Context context,
                                                  Style style,
                                                  LocationEngine locationEngine,
                                                  LocationEngineRequest locationEngineRequest,
                                                  int styleRes)

Deprecated. use LocationComponentActivationOptions.Builder instead

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(boolean).

Parameters:

context - the context

style - the proxy object for current map style. More info at Style

locationEngine - the engine, or null if you'd like to only force location updates

locationEngineRequest - the location request

styleRes - the LocationComponent style res

activateLocationComponent

@Deprecated
public void activateLocationComponent(android.content.Context context,
                                                  Style style,
                                                  LocationEngine locationEngine)

Deprecated. use LocationComponentActivationOptions.Builder instead

This method will show the location icon and enable the camera tracking the location.

Parameters:

context - the context

style - the proxy object for current map style. More info at Style

locationEngine - the engine

activateLocationComponent

@Deprecated
public void activateLocationComponent(android.content.Context context,
                                                  Style style,
                                                  LocationEngine locationEngine,
                                                  LocationEngineRequest locationEngineRequest)

Deprecated. use LocationComponentActivationOptions.Builder instead

This method will show the location icon and enable the camera tracking the location.

Parameters:

context - the context

style - the proxy object for current map style. More info at Style

locationEngine - the engine

locationEngineRequest - the location request

activateLocationComponent

@Deprecated
public void activateLocationComponent(android.content.Context context,
                                                  Style style,
                                                  LocationEngine locationEngine,
                                                  LocationComponentOptions options)

Deprecated. use LocationComponentActivationOptions.Builder instead

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(boolean).

Parameters:

locationEngine - the engine, or null if you'd like to only force location updates

style - the proxy object for current map style. More info at Style

options - the options

activateLocationComponent

@Deprecated
public void activateLocationComponent(android.content.Context context,
                                                  Style style,
                                                  LocationEngine locationEngine,
                                                  LocationEngineRequest locationEngineRequest,
                                                  LocationComponentOptions options)

Deprecated. use LocationComponentActivationOptions.Builder instead

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(boolean).

Parameters:

context - the context

style - the proxy object for current map style. More info at Style

locationEngine - the engine, or null if you'd like to only force location updates

locationEngineRequest - the location request

options - the options

activateLocationComponent

public void activateLocationComponent(LocationComponentActivationOptions activationOptions)

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(boolean).

Parameters:

activationOptions - a fully built LocationComponentActivationOptions object

setLocationComponentEnabled

public void setLocationComponentEnabled(boolean isEnabled)

Manage component's visibility after activation.

Parameters:

isEnabled - true if the plugin should be visible and listen for location updates, false otherwise.

isLocationComponentEnabled

public boolean isLocationComponentEnabled()

Returns whether the plugin is enabled, meaning that location can be displayed and camera modes can be used.

Returns:

true if the plugin is enabled, false otherwise

setCameraMode

public void setCameraMode(int cameraMode)

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(double) or tiltWhileTracking(double). 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

Parameters:

cameraMode - one of the modes found in CameraMode

setCameraMode

public void setCameraMode(int cameraMode,
                          OnLocationCameraTransitionListener transitionListener)

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(double) or tiltWhileTracking(double). 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

Parameters:

cameraMode - one of the modes found in CameraMode

transitionListener - callback that's going to be invoked when the transition animation finishes

setCameraMode

public void setCameraMode(int cameraMode,
                          long transitionDuration,
                          java.lang.Double zoom,
                          java.lang.Double bearing,
                          java.lang.Double tilt,
                          OnLocationCameraTransitionListener transitionListener)

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(double) or tiltWhileTracking(double). Use OnLocationCameraTransitionListener to listen for the transition state.

Set values of zoom, bearing and tilt 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

Parameters:

cameraMode - one of the modes found in CameraMode

transitionDuration - duration of the transition in milliseconds

zoom - target zoom, set to null to use current camera position

bearing - target bearing, set to null to use current camera position

tilt - target tilt, set to null to use current camera position

transitionListener - callback that's going to be invoked when the transition animation finishes

getCameraMode

public int getCameraMode()

Provides the current camera mode being used to track the location or compass updates.

Returns:

the current camera mode

setRenderMode

public void setRenderMode(int renderMode)

Sets the render mode, which determines how the location updates will be rendered on the map.

• RenderMode.NORMAL: Shows user location, bearing ignored
• RenderMode.COMPASS: Shows user location with bearing considered from compass
• RenderMode.GPS: Shows user location with bearing considered from location

Parameters:

renderMode - one of the modes found in RenderMode

getRenderMode

public int getRenderMode()

Provides the current render mode being used to show the location and/or compass updates on the map.

Returns:

the current render mode

getLocationComponentOptions

public LocationComponentOptions getLocationComponentOptions()

Returns the current location options being used.

Returns:

the current LocationComponentOptions

applyStyle

public void applyStyle(android.content.Context context,
                       int styleRes)

Apply a new component style with a style resource.

Parameters:

styleRes - a XML style overriding some or all the options

applyStyle

public void applyStyle(LocationComponentOptions options)

Apply a new component style with location component options.

Parameters:

options - to update the current style

zoomWhileTracking

public void zoomWhileTracking(double zoomLevel,
                              long animationDuration,
                              MapboxMap.CancelableCallback callback)

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(CameraUpdate), MapboxMap.easeCamera(CameraUpdate) or MapboxMap.animateCamera(CameraUpdate) 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.

Parameters:

zoomLevel - The desired zoom level.

animationDuration - The zoom animation duration.

callback - The callback with finish/cancel information

zoomWhileTracking

public void zoomWhileTracking(double zoomLevel,
                              long animationDuration)

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(CameraUpdate), MapboxMap.easeCamera(CameraUpdate) or MapboxMap.animateCamera(CameraUpdate) 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.

Parameters:

zoomLevel - The desired zoom level.

animationDuration - The zoom animation duration.

zoomWhileTracking

public void zoomWhileTracking(double zoomLevel)

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(CameraUpdate), MapboxMap.easeCamera(CameraUpdate) or MapboxMap.animateCamera(CameraUpdate) 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.

Parameters:

zoomLevel - The desired zoom level.

cancelZoomWhileTrackingAnimation

public void cancelZoomWhileTrackingAnimation()

Cancels animation started by zoomWhileTracking(double, long, MapboxMap.CancelableCallback).

paddingWhileTracking

public void paddingWhileTracking(double[] padding)

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(CameraUpdate), MapboxMap.easeCamera(CameraUpdate) or MapboxMap.animateCamera(CameraUpdate) 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.

Parameters:

padding - The desired padding.

paddingWhileTracking

public void paddingWhileTracking(double[] padding,
                                 long animationDuration)

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(CameraUpdate), MapboxMap.easeCamera(CameraUpdate) or MapboxMap.animateCamera(CameraUpdate) 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.

Parameters:

padding - The desired padding.

animationDuration - The padding animation duration.

paddingWhileTracking

public void paddingWhileTracking(double[] padding,
                                 long animationDuration,
                                 MapboxMap.CancelableCallback callback)

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(CameraUpdate), MapboxMap.easeCamera(CameraUpdate) or MapboxMap.animateCamera(CameraUpdate) 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.

Parameters:

padding - The desired padding.

animationDuration - The padding animation duration.

callback - The callback with finish/cancel information

cancelPaddingWhileTrackingAnimation

public void cancelPaddingWhileTrackingAnimation()

Cancels animation started by paddingWhileTracking(double[], long, MapboxMap.CancelableCallback).

tiltWhileTracking

public void tiltWhileTracking(double tilt,
                              long animationDuration,
                              MapboxMap.CancelableCallback callback)

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(CameraUpdate), MapboxMap.easeCamera(CameraUpdate) or MapboxMap.animateCamera(CameraUpdate) instead.

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

Parameters:

tilt - The desired camera tilt.

animationDuration - The tilt animation duration.

callback - The callback with finish/cancel information

tiltWhileTracking

public void tiltWhileTracking(double tilt,
                              long animationDuration)

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(CameraUpdate), MapboxMap.easeCamera(CameraUpdate) or MapboxMap.animateCamera(CameraUpdate) instead.

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

Parameters:

tilt - The desired camera tilt.

animationDuration - The tilt animation duration.

tiltWhileTracking

public void tiltWhileTracking(double tilt)

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(CameraUpdate), MapboxMap.easeCamera(CameraUpdate) or MapboxMap.animateCamera(CameraUpdate) instead.

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

Parameters:

tilt - The desired camera tilt.

cancelTiltWhileTrackingAnimation

public void cancelTiltWhileTrackingAnimation()

Cancels animation started by tiltWhileTracking(double, long, MapboxMap.CancelableCallback).

forceLocationUpdate

public void forceLocationUpdate(android.location.Location location)

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

Parameters:

location - where the location icon is placed on the map

forceLocationUpdate

public void forceLocationUpdate(java.util.List<android.location.Location> locations,
                                boolean lookAheadUpdate)

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

This method can be used to provide the list of locations where the last one is the target location and the rest are intermediate points used as the animation path. The puck and the camera will be animated between each of the points linearly until reaching the target.

Parameters:

locations - where the location icon is placed on the map

lookAheadUpdate - If set to true, the last location's timestamp has to be greater than current timestamp and should represent the time at which the animation should actually reach this position, cutting out the time interpolation delay.

setMaxAnimationFps

public void setMaxAnimationFps(int maxAnimationFps)

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(double)/tiltWhileTracking(double).

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:

 
 mapboxMap.addOnCameraIdleListener(new MapboxMap.OnCameraIdleListener() {
   {@literal @}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);
   }
 });
 
 

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

Parameters:

maxAnimationFps - max location animation FPS

setLocationEngine

public void setLocationEngine(LocationEngine locationEngine)

Set the location engine to update the current user location.

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

Parameters:

locationEngine - a LocationEngine this component should use to handle updates

setLocationEngineRequest

public void setLocationEngineRequest(LocationEngineRequest locationEngineRequest)

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

Parameters:

locationEngineRequest - the location request

getLocationEngineRequest

public LocationEngineRequest getLocationEngineRequest()

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

getLocationEngine

public LocationEngine getLocationEngine()

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

Returns:

the LocationEngine being used to update the user location

setCompassEngine

public void setCompassEngine(CompassEngine compassEngine)

Sets the compass engine used to provide compass heading values.

Parameters:

compassEngine - to be used

getCompassEngine

public CompassEngine getCompassEngine()

Returns the compass engine used to provide compass heading values.

Returns:

compass engine currently being used

getLastKnownLocation

public android.location.Location getLastKnownLocation()

Get the last know location of the location component.

Returns:

the last known location

addOnLocationClickListener

public void addOnLocationClickListener(OnLocationClickListener listener)

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, MapboxMap.OnMapClickListener.onMapClick(LatLng) is going to be consumed and not pushed to the listeners registered after the component's activation.

Parameters:

listener - The location click listener that is invoked when the location is clicked

removeOnLocationClickListener

public void removeOnLocationClickListener(OnLocationClickListener listener)

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

Parameters:

listener - to be removed

addOnLocationLongClickListener

public void addOnLocationLongClickListener(OnLocationLongClickListener listener)

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, MapboxMap.OnMapLongClickListener.onMapLongClick(LatLng) is going to be consumed and not pushed to the listeners registered after the component's activation.

Parameters:

listener - The location click listener that is invoked when the location is clicked

removeOnLocationLongClickListener

public void removeOnLocationLongClickListener(OnLocationLongClickListener listener)

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

Parameters:

listener - to be removed

addOnCameraTrackingChangedListener

public void addOnCameraTrackingChangedListener(OnCameraTrackingChangedListener listener)

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

Parameters:

listener - Listener that gets invoked when camera tracking state changes.

removeOnCameraTrackingChangedListener

public void removeOnCameraTrackingChangedListener(OnCameraTrackingChangedListener listener)

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

Parameters:

listener - Listener that gets invoked when camera tracking state changes.

addOnRenderModeChangedListener

public void addOnRenderModeChangedListener(OnRenderModeChangedListener listener)

Adds a listener that gets invoked when render mode changes.

Parameters:

listener - Listener that gets invoked when render mode changes.

removeRenderModeChangedListener

public void removeRenderModeChangedListener(OnRenderModeChangedListener listener)

Removes a listener that gets invoked when render mode changes.

Parameters:

listener - Listener that gets invoked when render mode changes.

addOnLocationStaleListener

public void addOnLocationStaleListener(OnLocationStaleListener listener)

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().

Parameters:

listener - invoked when last update is considered stale

removeOnLocationStaleListener

public void removeOnLocationStaleListener(OnLocationStaleListener listener)

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

Parameters:

listener - to be removed from the list

addOnIndicatorPositionChangedListener

public void addOnIndicatorPositionChangedListener(OnIndicatorPositionChangedListener listener)

Adds a listener that gets invoked when indicator position changes.

Parameters:

listener - Listener that gets invoked when indicator position changes

removeOnIndicatorPositionChangedListener

public void removeOnIndicatorPositionChangedListener(OnIndicatorPositionChangedListener listener)

Removes a listener that gets invoked when indicator position changes.

Parameters:

listener - Listener that gets invoked when indicator position changes.

onStart

public void onStart()

Internal use.

onStop

public void onStop()

Internal use.

onDestroy

public void onDestroy()

Internal use.

onStartLoadingMap

public void onStartLoadingMap()

Internal use.

onFinishLoadingStyle

public void onFinishLoadingStyle()

Internal use.

isLocationComponentActivated

public boolean isLocationComponentActivated()

Returns whether the location component is activated.

Returns:

true if the component is activated, false otherwise