Navigation layer
In NaviKit SDK, NavigationLayer is an additional map layer that includes the user interface (routes, route points, the user placemark, and balloons) and its display logic. NavigationLayer also provides the camera API that lets you change the map position based on navigation scenarios like tracking the user placemark, route overview, and free mode.
Create
To create a new navigation layer, use the NavigationLayerFactory.createNavigationLayer.
val navigationLayer = NavigationLayerFactory.createNavigationLayer(
mapWindow,
roadEventsLayer,
navigationStyleProvider,
navigation
)
To create roadEventsLayer, follow these instructions. To create navigation, follow these instructions.
After you create NavigationLayer, a mark with the current user location will be shown on the map if Navigation has location tracking enabled.
NavigationStyleProvider
To manage UI elements in the navigation layer, use the NavigationStyleProvider interface.
By implementing NavigationStyleProvider, you can set the style of individual UI elements using the required style provider.
- Route polylines: RouteViewStyleProvider.
- Alternate route and maneuver balloons: BalloonImageProvider.
- Route points: RequestPointStyleProvider.
- User placemark model: UserPlacemarkStyleProvider.
- Route pins: RoutePinsStyleProvider. Includes traffic light pins and route warnings.
The AutomotiveNavigationStyleProvider class is a ready-made implementation of the NavigationStyleProvider interface with UI elements in the signature style of API Maps. It's provided as a separate dependency.
To change some UI element styles, implement a new NavigationStyleProvider using AutomotiveNavigationStyleProvider as a delegate:
class NavigationStyleProviderImpl(private val context: Context) : NavigationStyleProvider {
private val styleProvider = AutomotiveNavigationStyleProvider(context)
// Default style provider implementation
override fun balloonImageProvider() = styleProvider.balloonImageProvider()
override fun requestPointStyleProvider() = styleProvider.requestPointStyleProvider()
override fun userPlacemarkStyleProvider() = styleProvider.userPlacemarkStyleProvider()
override fun routePinsStyleProvider() = styleProvider.routePinsStyleProvider()
// Override the route style logic
override fun routeViewStyleProvider(): RouteViewStyleProvider {
return object : RouteViewStyleProvider {
private val routeViewStyleProvider = styleProvider.routeViewStyleProvider()
override fun provideRouteStyle(
flags: Flags,
isSelected: Boolean,
isNightMode: Boolean,
routeStyle: RouteStyle
) {
routeViewStyleProvider.provideRouteStyle(flags, isSelected, isNightMode, routeStyle)
// Only the current route will display traffic jams
routeStyle.setShowJams(isSelected)
}
// Implementations of other methods through routeViewStyleProvider ...
}
}
}
That way you can implement a separate RouteViewStyleProvider style provider for the route line and change how traffic is displayed on routes. Other UI elements are implemented as usual with the AutomotiveNavigationStyleProvider delegate.
The NavigationStyleProvider styles are refreshed with every call to NavigationLayer.refreshStyle.
There's a detailed example of NavigationStyleProvider implementation in the demo app.
Routes
The navigation layer is responsible for displaying routes in Navigation.
Route display
The navigation layer can display routes on the map. Routes are rendered according to the following scenario:
- When you create NavigationLayer, the Navigation object is passed to it. The layer uses the object to listen to the navigation status and track route changes. For example, when routes are requested, navigation informs you that a route was requested using the NavigationListener.onRoutesRequested event handler, and the layer switches the camera to route overview mode.
- Navigation then informs you that routes have been built successfully, the NavigationListener.onRoutesBuilt method is called, and the layer displays routes on the map using the updated data.
That's how the navigation layer tracks route states in Navigation, displays them on the map, and changes them when needed.
Instant guidance
To skip the comparison of alternate routes in overview mode and start guidance along the first found route, start guidance straight after route request results are received in the NavigationListener.onRoutesBuilt event handler method.
When routes have been requested but guidance hasn't yet started, you may notice that UI routes "blink". Avoid that by hiding the navigation layer UI before starting guidance. Use the NavigationLayer.setIsVisible method or hide the route lines using style override through NavigationStyleProvider.
Route sources
NavigationLayer.getRoutesSource determines the type of routes the navigation layer is currently displaying:
- NAVIGATION: The result of a route request via Navigation when routes are displayed in overview mode.
- GUIDANCE: The current route during guidance when routes are displayed in guidance mode.
Current route
NavigationLayer stores information about the currently selected route. By calling NavigationLayer.selectRoute, you can change the currently selected route in overview mode.
Here's an example of how to set the current route:
val routeViewListener = object : RouteViewListener {
override fun onRouteViewTap(routeView: RouteView) {
when (navigationLayer.routesSource) {
RoutesSource.NAVIGATION -> navigationLayer.selectRoute(routeView)
RoutesSource.GUIDANCE -> navigationLayer.navigation.guidance.switchToRoute(routeView.route)
}
}
override fun onRouteViewsChanged() {
if (navigationLayer.selectedRoute() != null) return
val route = navigationLayer.routes.firstOrNull() ?: return
navigationLayer.selectRoute(route)
}
}
navigationLayer.addRouteViewListener(routeViewListener)
To track route states in the navigation layer, use the RouteViewListener interface.
- RouteViewListener.onRouteViewsChanged informs you about route changes in NavigationLayer. If the selected route isn't there, the fastest (first) route is selected instead.
- RouteViewListener.onRouteViewTap processes the event of tapping the route line on the map.
Note
The navigation layer doesn't contain the current route by default after routes are requested through Navigation. You have to set it manually, for example, using RouteViewListener.onRouteViewsChanged.
Route points
The navigation layer is responsible for displaying the from, to, and via points in guidance and overview modes.
To track point changes and taps, use the RequestPointListener interface.
User placemark
A user placemark is a model that displays the current user location and direction on the map. It consists of an OBJ file and PNG texture.
Balloons
Balloons are UI elements with text on the map. There are different types of balloons:
- Maneuver balloons show the next maneuver on the map in guidance mode.
- Alternative balloons show route information in overview mode and compare the current and selected routes.
Use the BalloonViewListener interface to follow balloon events.
Camera
To manage the camera, use the Camera object by calling NavigationLayer.getCamera.
To switch between camera modes, use the Camera.setCameraMode method. Supported modes:
- Following: The user placemark tracked by the camera during guidance.
- Overview: An overview of requested routes.
- Free: The default mode.
By default, Camera has full control over the map and automatically changes the camera status. When using special camera modes, you may want to restrict camera permissions.
With the Camera and NavigationLayer methods, you can change the following camera parameters:
- Automatic zoom-in.
- Automatic turn.
- Automatic switch between camera modes.
- Zoom-in correction parameter in guidance mode.
- 2D mode on/off.
If you create a complex interface over the map, UI elements may cover some map areas. You can prevent that by configuring the visible area parameters.
Supported settings for the visible map area:
- Camera.setOverviewRectWith: Determines the map area where routes are displayed in overview mode.
- Camera.setExtraOverviewPoints: Sets a list of points that must be visible on the map in overview mode.