com.mapbox.services.android.navigation.ui.v5.map

Class NavigationMapboxMap

java.lang.Object

com.mapbox.services.android.navigation.ui.v5.map.NavigationMapboxMap

public class NavigationMapboxMap
extends java.lang.Object

Wrapper class for MapboxMap.

This class initializes various map-related components and plugins that are useful for providing a navigation-driven map experience.

These APIs include drawing a route line, camera animations, and more.

Constructor Summary

Constructors

Constructor and Description
NavigationMapboxMap(com.mapbox.mapboxsdk.maps.MapView mapView, com.mapbox.mapboxsdk.maps.MapboxMap mapboxMap) Constructor that can be used once OnMapReadyCallback has been called via MapView.getMapAsync(OnMapReadyCallback).

Method Summary

Modifier and Type	Method and Description
void	addMarker(android.content.Context context, com.mapbox.geojson.Point position) Adds a marker icon on the map at the given position.
void	addOnCameraTrackingChangedListener(com.mapbox.mapboxsdk.location.OnCameraTrackingChangedListener listener) Add a OnCameraTrackingChangedListener to the LocationComponent that is wrapped within this class.
boolean	addOnWayNameChangedListener(OnWayNameChangedListener listener) Add a OnWayNameChangedListener for listening to updates to the way name shown on the map below the location icon.
void	addProgressChangeListener(com.mapbox.services.android.navigation.v5.navigation.MapboxNavigation navigation) Can be used to automatically drive the map camera / route updates and arrow once navigation has started.
void	adjustLocationIconWith(int[] customPadding) Use this method to position the location icon on the map.
void	clearMarkers() Clears all markers on the map that have been added by this class.
void	drawRoute(com.mapbox.api.directions.v5.models.DirectionsRoute route) Will draw the given DirectionsRoute on the map using the colors defined in your given style.
void	drawRoutes(java.util.List<com.mapbox.api.directions.v5.models.DirectionsRoute> routes) Will draw the given list of DirectionsRoute on the map using the colors defined in your given style.
boolean	isIncidentsVisible() Returns true if the map has incidents layers and they are visible and will return false otherwise.
boolean	isTrafficVisible() Returns true if the map has traffic layers and they are visible and will return false otherwise.
void	onStart() Should be used in FragmentActivity.onStart() to ensure proper accounting for the lifecycle.
void	onStop() Should be used in FragmentActivity.onStop() to ensure proper accounting for the lifecycle.
void	removeOnCameraTrackingChangedListener(com.mapbox.mapboxsdk.location.OnCameraTrackingChangedListener listener) Remove a OnCameraTrackingChangedListener from the LocationComponent that is wrapped within this class.
boolean	removeOnWayNameChangedListener(OnWayNameChangedListener listener) Remove a OnWayNameChangedListener for listening to updates to the way name shown on the map below the location icon.
void	removeRoute() Will remove the drawn route displayed on the map.
void	resetCameraPositionWith(int trackingCameraMode) Resets the map camera / padding to the last known camera position.
void	resetPadding() This method resets the map padding to the default padding that is generated when navigation begins (location icon moved to lower half of the screen) or the custom padding that was last passed via MapPaddingAdjustor.adjustLocationIconWith(int[]).
void	restoreFrom(NavigationMapboxMapInstanceState instanceState) Can be used to restore a NavigationMapboxMap after it has been initialized.
void	resumeCamera(android.location.Location location) Centers the map camera around the provided Location.
NavigationCamera	retrieveCamera() Provides the camera being used to animate the map camera positions along the route, driven by the progress change listener.
com.mapbox.mapboxsdk.maps.MapboxMap	retrieveMap() Provides the MapboxMap originally given in the constructor.
void	saveStateWith(java.lang.String key, android.os.Bundle outState) Can be used to store the current state of the map in Activity.onSaveInstanceState(Bundle, PersistableBundle).
void	setOnRouteSelectionChangeListener(OnRouteSelectionChangeListener listener) Set a OnRouteSelectionChangeListener to know which route the user has currently selected as their primary route.
void	showAlternativeRoutes(boolean alternativesVisible) Toggle whether or not you'd like the map to display the alternative routes.
void	showRouteOverview(int[] padding) Adjusts the map camera to DirectionsRoute being traveled along.
void	startCamera(com.mapbox.api.directions.v5.models.DirectionsRoute directionsRoute) Centers the map camera to the beginning of the provided DirectionsRoute.
void	takeScreenshot(NavigationSnapshotReadyCallback navigationSnapshotReadyCallback)
void	updateCameraTrackingMode(int trackingMode) Updates the NavigationCamera.TrackingMode that will be used when camera tracking is enabled.
void	updateIncidentsVisibility(boolean isVisible) Updates the visibility of incidents layers on the map (if any exist).
void	updateLocation(android.location.Location location) Updates the location icon on the map and way name data (if found) for the given Location.
void	updateLocationLayerRenderMode(int renderMode) Updates how the user location is shown on the map.
void	updateLocationVisibilityTo(boolean isVisible) Hide or show the location icon on the map.
void	updateMapFpsThrottle(int maxFpsThreshold) The maximum preferred frames per second at which to render the map.
void	updateMapFpsThrottleEnabled(boolean isEnabled) Enabled by default, the navigation map will throttle frames per second when the application has limited resources, such as when the device is running on battery power.
void	updateTrafficVisibility(boolean isVisible) Updates the visibility of traffic layers on the map (if any exist).
void	updateWaynameQueryMap(boolean isEnabled) Enables or disables the way name chip underneath the location icon.

Methods inherited from class java.lang.Object

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

Constructor Detail

NavigationMapboxMap

public NavigationMapboxMap(@NonNull
                           com.mapbox.mapboxsdk.maps.MapView mapView,
                           @NonNull
                           com.mapbox.mapboxsdk.maps.MapboxMap mapboxMap)

Constructor that can be used once OnMapReadyCallback has been called via MapView.getMapAsync(OnMapReadyCallback).

Parameters:

mapView - for map size and Context

mapboxMap - for APIs to interact with the map

Method Detail

addMarker

public void addMarker(android.content.Context context,
                      com.mapbox.geojson.Point position)

Adds a marker icon on the map at the given position.

The icon used for this method can be defined in your theme with the attribute navigationViewDestinationMarker.

Parameters:

context - to retrieve the icon drawable from the theme

position - the point at which the marker will be placed

clearMarkers

public void clearMarkers()

Clears all markers on the map that have been added by this class.

This will not clear all markers from the map entirely. Does nothing if no markers have been added.

updateLocation

public void updateLocation(android.location.Location location)

Updates the location icon on the map and way name data (if found) for the given Location.

Parameters:

location - to update the icon and query the map

updateMapFpsThrottle

public void updateMapFpsThrottle(int maxFpsThreshold)

The maximum preferred frames per second at which to render the map.

This property only takes effect when the application has limited resources, such as when the device is running on battery power. By default, this is set to 20fps.

Throttling will also only take effect when the camera is currently tracking the user location.

Parameters:

maxFpsThreshold - to be used to limit map frames per second

updateMapFpsThrottleEnabled

public void updateMapFpsThrottleEnabled(boolean isEnabled)

Enabled by default, the navigation map will throttle frames per second when the application has limited resources, such as when the device is running on battery power.

Throttling will also only take effect when the camera is currently tracking the user location.

Parameters:

isEnabled - true to enable (default), false to render at device ability

updateLocationLayerRenderMode

public void updateLocationLayerRenderMode(int renderMode)

Updates how the user location is shown 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 - GPS, NORMAL, or COMPASS

addProgressChangeListener

public void addProgressChangeListener(com.mapbox.services.android.navigation.v5.navigation.MapboxNavigation navigation)

Can be used to automatically drive the map camera / route updates and arrow once navigation has started.

These will automatically be removed in MapboxNavigation.onDestroy().

Parameters:

navigation - to add the progress listeners

saveStateWith

public void saveStateWith(java.lang.String key,
                          android.os.Bundle outState)

Can be used to store the current state of the map in Activity.onSaveInstanceState(Bundle, PersistableBundle).

This method uses NavigationMapboxMapInstanceState, stored with the provided key. This key can also later be used to extract the NavigationMapboxMapInstanceState.

Parameters:

key - used to store the state

outState - to store state variables

restoreFrom

public void restoreFrom(NavigationMapboxMapInstanceState instanceState)

Can be used to restore a NavigationMapboxMap after it has been initialized.

This cannot be called in Activity.onRestoreInstanceState(Bundle) because we cannot guarantee the map is re-initialized at that point.

You can extract the NavigationMapboxMapInstanceState in onRestoreInstanceState and then restore the map once it's ready.

Parameters:

instanceState - to extract state variables

drawRoute

public void drawRoute(@NonNull
                      com.mapbox.api.directions.v5.models.DirectionsRoute route)

Will draw the given DirectionsRoute on the map using the colors defined in your given style.

Parameters:

route - to be drawn

drawRoutes

public void drawRoutes(@NonNull
                       java.util.List<com.mapbox.api.directions.v5.models.DirectionsRoute> routes)

Will draw the given list of DirectionsRoute on the map using the colors defined in your given style.

The primary route will default to the first route in the directions route list. All other routes in the list will be drawn on the map using the alternative route style.

Parameters:

routes - to be drawn

setOnRouteSelectionChangeListener

public void setOnRouteSelectionChangeListener(@NonNull
                                              OnRouteSelectionChangeListener listener)

Set a OnRouteSelectionChangeListener to know which route the user has currently selected as their primary route.

Parameters:

listener - a listener which lets you know when the user has changed the primary route and provides the current direction route which the user has selected

showAlternativeRoutes

public void showAlternativeRoutes(boolean alternativesVisible)

Toggle whether or not you'd like the map to display the alternative routes. This option can be used for when the user actually begins the navigation session and alternative routes aren't needed anymore.

Parameters:

alternativesVisible - true if you'd like alternative routes to be displayed on the map, else false

removeRoute

public void removeRoute()

Will remove the drawn route displayed on the map. Does nothing if no route is drawn.

retrieveCamera

public NavigationCamera retrieveCamera()

Provides the camera being used to animate the map camera positions along the route, driven by the progress change listener.

Returns:

camera used to animate map

updateCameraTrackingMode

public void updateCameraTrackingMode(int trackingMode)

Updates the NavigationCamera.TrackingMode that will be used when camera tracking is enabled.

Parameters:

trackingMode - the tracking mode

Since:

0.21.0

startCamera

public void startCamera(@NonNull
                        com.mapbox.api.directions.v5.models.DirectionsRoute directionsRoute)

Centers the map camera to the beginning of the provided DirectionsRoute.

Parameters:

directionsRoute - to update the camera position

resumeCamera

public void resumeCamera(@NonNull
                         android.location.Location location)

Centers the map camera around the provided Location.

Parameters:

location - to update the camera position

resetCameraPositionWith

public void resetCameraPositionWith(int trackingCameraMode)

Resets the map camera / padding to the last known camera position.

You can also specify a tracking mode to reset with. For example if you would like to reset the camera and continue tracking, you would use NavigationCamera.NAVIGATION_TRACKING_MODE_GPS.

Parameters:

trackingCameraMode - the tracking mode

resetPadding

public void resetPadding()

This method resets the map padding to the default padding that is generated when navigation begins (location icon moved to lower half of the screen) or the custom padding that was last passed via MapPaddingAdjustor.adjustLocationIconWith(int[]).

The custom padding will be used if it exists, otherwise the default will be used.

showRouteOverview

public void showRouteOverview(int[] padding)

Adjusts the map camera to DirectionsRoute being traveled along.

Also includes the given padding.

Parameters:

padding - for creating the overview camera position

updateWaynameQueryMap

public void updateWaynameQueryMap(boolean isEnabled)

Enables or disables the way name chip underneath the location icon.

Parameters:

isEnabled - true to enable, false to disable

onStart

public void onStart()

Should be used in FragmentActivity.onStart() to ensure proper accounting for the lifecycle.

onStop

public void onStop()

Should be used in FragmentActivity.onStop() to ensure proper accounting for the lifecycle.

updateLocationVisibilityTo

public void updateLocationVisibilityTo(boolean isVisible)

Hide or show the location icon on the map.

Parameters:

isVisible - true to show, false to hide

retrieveMap

public com.mapbox.mapboxsdk.maps.MapboxMap retrieveMap()

Provides the MapboxMap originally given in the constructor.

This method gives access to all map-related APIs.

Returns:

map provided in the constructor

updateIncidentsVisibility

public void updateIncidentsVisibility(boolean isVisible)

Updates the visibility of incidents layers on the map (if any exist).

Parameters:

isVisible - true if incidents should be visible, false otherwise

isIncidentsVisible

public boolean isIncidentsVisible()

Returns true if the map has incidents layers and they are visible and will return false otherwise.

Returns:

true if the map has incidents layers and they are visible, false otherwise

updateTrafficVisibility

public void updateTrafficVisibility(boolean isVisible)

Updates the visibility of traffic layers on the map (if any exist).

Parameters:

isVisible - true if traffic should be visible, false otherwise

isTrafficVisible

public boolean isTrafficVisible()

Returns true if the map has traffic layers and they are visible and will return false otherwise.

Returns:

true if the map has traffic layers and they are visible, false otherwise

addOnCameraTrackingChangedListener

public void addOnCameraTrackingChangedListener(com.mapbox.mapboxsdk.location.OnCameraTrackingChangedListener listener)

Add a OnCameraTrackingChangedListener to the LocationComponent that is wrapped within this class.

This listener will fire any time camera tracking is dismissed or the camera mode is updated.

Parameters:

listener - to be added

removeOnCameraTrackingChangedListener

public void removeOnCameraTrackingChangedListener(com.mapbox.mapboxsdk.location.OnCameraTrackingChangedListener listener)

Remove a OnCameraTrackingChangedListener from the LocationComponent that is wrapped within this class.

Parameters:

listener - to be removed

addOnWayNameChangedListener

public boolean addOnWayNameChangedListener(OnWayNameChangedListener listener)

Add a OnWayNameChangedListener for listening to updates to the way name shown on the map below the location icon.

Parameters:

listener - to be added

Returns:

true if added, false if listener was not found

removeOnWayNameChangedListener

public boolean removeOnWayNameChangedListener(OnWayNameChangedListener listener)

Remove a OnWayNameChangedListener for listening to updates to the way name shown on the map below the location icon.

Parameters:

listener - to be removed

Returns:

true if removed, false if listener was not found

adjustLocationIconWith

public void adjustLocationIconWith(int[] customPadding)

Use this method to position the location icon on the map.

For example, to position the icon in the center of the map, you can pass {0, 0, 0, 0} which eliminates the default padding we provide when navigation begins.

Parameters:

customPadding - true if should be centered on the map, false to position above the bottom view

takeScreenshot

public void takeScreenshot(NavigationSnapshotReadyCallback navigationSnapshotReadyCallback)