UI components

VERSION 0.3.34
PUBLIC PREVIEW

Navigation SDK for Android is only available upon request. Contact us to get started.

The Navigation SDK provides an attractive UI components for displaying navigation information. The UI components are provided as a separate module. Before using it, add its dependency to your module’s build.gradle.

1dependencies {
2 implementation "com.tomtom.sdk:navigation-ui:0.3.34"
3}

The UI components module includes the Text-To-Speech (TTS) component.

The module provides two main components that can be used to build your own navigation app. The first one is NavigationView, an Android ViewGroup subclass that can be used like a standard view to build a screen. NavigationView provides all the methods needed to configure views for navigation. The second one is NavigationFragment, another Android Fragment subclass that wraps both the whole NavigationView and TomTomNavigation. The main difference between NavigationFragment and NavigationView is that NavigationView requires you to handle all navigation events yourself, while the NavigationFragment does it inside a class and automatically updates the view states.

This UI component can be used to display all navigation information. It requires you to update views yourself. If you would prefer not to do this, you can use the NavigationFragment.

NavigationView consists of the following views:

  • Guidance view
  • Street view
  • Speed view
  • Arrival view

The UI components support both portrait and landscape modes.

center

center

Guidance view

Guidance view is the container for:

  • Next instruction view
  • Route line progress view
  • Estimated time of arrival (ETA) view
  • Lane guidance view
  • Combined instruction view
  • Route updated view

You can set a listener to monitor guidance view boundary changes.

1val onGuidanceViewBoundariesChangeListener =
2 OnGuidanceViewBoundariesChangeListener { viewBoundaries: ViewBoundaries ->
3 /* YOUR CODE GOES HERE */
4 }
5navigationView.addGuidanceViewBoundariesChangeListener(
6 onGuidanceViewBoundariesChangeListener
7)

Once it is no longer needed, you can remove it.

1navigationView.removeGuidanceViewBoundariesChangeListener(
2 onGuidanceViewBoundariesChangeListener
3)

Next instruction view

Displays information about the next maneuver, distance to that maneuver, and the name of the street the maneuver ends on. The user can also mute/unmute voice guidance by tapping the sound toggle button.

Instruction panel

NavigationView provides a set of methods to configure this view.

1val instruction = ForkGuidanceInstruction(
2 id = UniqueId(),
3 routeOffset = Distance.ofMeters(2000),
4 travelTime = Duration.ZERO,
5 maneuverPoint = GeoCoordinate(52.377956, 4.897070),
6 junctionType = JunctionType.REGULAR,
7 drivingSide = DrivingSide.RIGHT,
8 isPossibleToCombineWithNext = false,
9 nextSignificantRoad = RoadInformation(
10 roadName = "Piet Heinkade",
11 roadNumbers = listOf("s100"),
12 roadShields = listOf(RoadShield(fullRoadNumber = "s100", shieldContent = "100"))
13 ),
14 signpost = Signpost(exitNumber = "25"),
15 forkDirection = ForkDirection.LEFT
16)
17navigationView.setNextInstruction(instruction)
18navigationView.setDistanceToManeuver(Distance.ofMeters(1700), Units.METRIC)
19navigationView.setGuidanceInstructionText("Piet Heinkade")
20navigationView.setRoadShields(listOf("s100"))
21navigationView.setMotorwayExit("25")
22navigationView.setAudioState(enabled = true)
23navigationView.setAudioToggleButtonClickListener { view: View ->
24 /* YOUR CODE GOES HERE */
25}

Route line progress view

Shows the progress along the route.

Navigation route line

To set the progress, call setRouteLineProgress(routeLength, traveledDistance).

Estimated time of arrival (ETA) view

Displays information about the arrival time, remaining distance, and remaining time. It also contains a cancel button to enable the user to stop navigation.

ETA panel

The NavigationView has methods to set up properties for this view.

1navigationView.setArrivalTime(DateTime(2022, 6, 14, 13, 25))
2navigationView.setDistanceToDestination(Distance.ofMeters(3800), Units.METRIC)
3navigationView.setTravelTime(Duration.ofMinutes(8))

Set a listener to handle cancel button click events.

1navigationView.setCancelButtonClickListener { view: View ->
2 /* YOUR CODE GOES HERE */
3}

Lane guidance view

Indicates what lane(s) the user should drive on.

Lane guidance

The lane guidance view fits into the place of the ETA view. The user can close it by tapping on it.

Panel with lane guidance

To set the lanes call setLanes(List<Lane>). If the list is empty, lane guidance view will be hidden.

Combined instruction view

Shows the user the maneuver coming immediately after the next one.

Combined instruction

This view is shown in the place of the ETA view. If the user taps it, it closes.

Panel with combined instruction

The NavigationView allows you to set the combined instruction.

navigationView.setCombinedManeuver(AnnouncementManeuver.TurnLeft)

You can also hide it.

navigationView.hideCombinedInstructionView()

Route updated view

Notifies the user that the route has been updated.

Route updated notyfication

This view is shown in the place of the ETA view. The user can close it by tapping on it.

Panel with route updated notyfication

To show a route updated notification, call showRouteUpdatedView().

Street view

Displays the current street name.

Street name

To set the content for the street view, call setStreetText(String). You can manage the visibility of this view via showStreetView() and hideStreetView().

Speed view

Displays the speed limit on the current street and the user’s current speed.

Speed view

The NavigationView supports setting the click listener on the speed limit and current speed views.

1navigationView.setSpeedLimitClickListener { view: View ->
2 /* YOUR CODE GOES HERE */
3}
1navigationView.setCurrentSpeedClickListener { view: View ->
2 /* YOUR CODE GOES HERE */
3}

You can also change the visibility of the whole Speed view programmatically.

navigationView.showSpeedView()
navigationView.hideSpeedView()

Arrival view

Shown when the ArrivalDetectionEngine detects that the user has reached the destination. The finish button on the view stops navigation.

Arrival

You can set the description for the arrival destination to be either an address or the name of the location.

navigationView.setArrivalDescription(destinationAddress)

To show the view call showArrivalView().

To handle clicks on the finish button, set the listener.

1navigationView.setArrivalViewButtonClickListener { view: View ->
2 /* YOUR CODE GOES HERE */
3}

All of the above UI components are part of NavigationFragment. You can access NavigationView from NavigationFragment by calling NavigationFragment.navigationView.

NavigationFragment is not only the UI component container, but also the wrapper for TomTomNavigation. If you want navigation to manage all the views, use NavigationFragment. NavigationFragment handles all events from navigation internally and automatically updates the views.

See how to create TomTomNavigation in the Quickstart guide.

Initialization

NavigationFragment can be instantiated either programmatically or via XML view inflation.

Programmatically

First, define NavigationUiOptions to configure the UI options. To do so, use NavigationUiOptions.Builder. You can set following properties:

  • units - Sets the Units of the distance displayed before upcoming maneuvers. Set by default to the units from the device’s locale settings.
  • isSoundEnabled - Sets whether or not voice guidance should be used. Sound is enabled by default.
  • keepInBackground - Sets whether or not the navigation should be kept in the background within Android Service. By default it is set to false.
  • voiceLanguage - Sets the language for voice guidance. The default language is US English.

Note that you can keep navigation in the background using the Android Service. A notification will appear reporting that navigation is running. The service will be disconnected when NavigationFragment is destroyed.

Use the created NavigationUiOptions object to instantiate the NavigationFragment with its NavigationFragment.newInstance(NavigationUiOptions) method.

1val navigationUiOptions = NavigationUiOptions.Builder()
2 .voiceLanguage(Locale.getDefault())
3 .keepInBackground(true)
4 .soundEnabled(false)
5 .units(Units.METRIC)
6 .build()
7val navigationFragment = NavigationFragment.newInstance(navigationUiOptions)

Once NavigationFragment is created, add it to the container created in your layout. To do this, use FragmentManager.

1supportFragmentManager.beginTransaction()
2 .add(R.id.navigation_fragment_container, navigationFragment)
3 .commitNow()
1<androidx.fragment.app.FragmentContainerView
2 android:id="@+id/navigation_fragment_container"
3 android:layout_width="match_parent"
4 android:layout_height="match_parent"/>

XML view inflation

  1. Add a fragment container for NavigationFragment.
  2. Declare the TomTom namespace xmlns:tomtom="http://schemas.android.com/apk/res-auto".
  3. Provide the android:name="com.tomtom.sdk.navigation.ui.NavigationFragment" property to the fragment.
  4. You can specify the same properties as by using NavigationUiOptions.
1<androidx.fragment.app.FragmentContainerView
2 xmlns:tomtom="http://schemas.android.com/apk/res-auto"
3 android:id="@+id/navigation_fragment"
4 android:name="com.tomtom.sdk.navigation.ui.NavigationFragment"
5 android:layout_width="match_parent"
6 android:layout_height="match_parent"
7 tomtom:units="Metric"
8 tomtom:soundEnabled="false"
9 tomtom:keepInBackground="true"
10 tomtom:voiceLanguage="pl-PL" />
  1. At this point, you can obtain the NavigationFragment object in the code by using FragmentManager.
val navigationFragment =
supportFragmentManager.findFragmentById(R.id.navigation_fragment) as NavigationFragment

Listeners

If you’re using NavigationFragment, all of the TomTomNavigation listeners are still valid. Read about them in the turn-by-turn navigation guide or in the free driving guide.

You can also set the NavigationListener to listen to navigation events.

  • onStarted() - Called when navigation has started.
  • onFailed(NavigationError) - Called when an error occurred during navigation.
  • onStopped() - Called when the cancel button on the ETA view or the finish button on the arrival view is clicked. You need to stop navigation and dispose of it yourself.
1val navigationListener = object : NavigationFragment.NavigationListener {
2 override fun onStarted() {
3 /* YOUR CODE GOES HERE */
4 }
5
6 override fun onFailed(error: NavigationError) {
7 /* YOUR CODE GOES HERE */
8 }
9
10 override fun onStopped() {
11 /* YOUR CODE GOES HERE */
12 }
13}
14navigationFragment.addNavigationListener(navigationListener)

If the listener is no longer needed it can be removed.

navigationFragment.removeNavigationListener(navigationListener)

NavigationFragment is a wrapper for TomTomNavigation. This means you have to set TomTomNavigation to the fragment. This must be done before any of the following methods are called:

navigationFragment.setTomTomNavigation(tomTomNavigation)

Once TomTomNavigation is set, you can start navigation.

Free driving

Navigation can also be used in free driving mode, without a route. Read more about free driving mode here.

To start navigation without a route, call the startNavigation() method.

navigationFragment.startNavigation()

In free driving mode, only the Speed view and Street view are visible.

center

Turn-by-turn navigation

In turn-by-turn navigation mode, the Navigation SDK provides UI components that help the user to follow the route. It shows progress along the route, the next maneuver, the estimated arrival time and the remaining distance and time to the destination. As with free driving mode, the Speed view and Street view are also visible.

Navigation fragment

If you have a Route (see how to request the Route in the Planning a route guide), you can start navigation. Detailed information about turn-by-turn navigation can be found in this guide. Use the Route object and the RoutingOptions that were used during route planning to create a RoutePlan object.

You have to set the InstructionType in order to use properly the navigation panel.

The RoutePlan object is used to start navigation with the provided route.

1val amsterdam = GeoCoordinate(52.377956, 4.897070)
2val rotterdam = GeoCoordinate(51.926517, 4.462456)
3val routingOptions = RoutingOptions.Builder(Itinerary(amsterdam, rotterdam))
4 .instructionType(InstructionType.TEXT)
5 .build()
6// NOTE: Route request...
7val routePlan = RoutePlan(route = route, routingOptions = routingOptions)
8navigationFragment.startNavigation(routePlan)

The displayed UI component makes the chevron hover over the map. That operation requires map padding to be set. The padding values are specified in pixels.

1val bottomPaddingInDp = 262
2val bottomPaddingInPixels = (bottomPaddingInDp * resources.displayMetrics.density).toInt()
3tomTomMap.setPadding(Padding(left = 0, right = 0, top = 0, bottom = bottomPaddingInPixels))

You can check the size of the navigation panel and observe its changes using the Guidance view.

In addition, if the Route contains a LaneSection list, the NavigationFragment will show the Lane guidance view when required. To make lane guidance more precise, the Route should also contain a SpeedLimitSection list.

Lane guidance

Voice guidance

NavigationFragment provides voice guidance as well as visual guidance. The voice guidance requires that RouteLegs of the Route contain Instructions with verbal Announcements. The announcements on the motorway should be triggered further from the instruction point than default. To do it the Route has to contain list of MotorwaySection.

You can change the units used by voice guidance with GuidanceEngineOptions in GuidanceEngine.

You can also change the TextToSpeechEngine used to synthesize audio instructions. To do this, use the changeTextToSpeechEngine(TextToSpeechEngine) method. Read more about the TextToSpeechEngine here.

NavigationFragment also allows you to change the TTS language.

navigationFragment.changeAudioLanguage(Locale.ENGLISH)

Distance and speed units

NavigationFragment allows you to set the units for displaying distance and speed.

navigationFragment.setUnits(Units.METRIC)

Update

The Route that navigation is following can be updated at any time. To do this, create a new RoutePlan and call the update(RoutePlan) method.

val newRoutePlan = RoutePlan(route = newRoute, routingOptions = newRoutingOptions)
navigationFragment.update(newRoutePlan)

Read more about updating the Route in the route replanning guide.

Stop

The navigation has to be stopped manually even if the user reaches the destination. To do this, call the stopNavigation() method.

navigationFragment.stopNavigation()

It stops the underlying TomTomNavigation and stops showing the UI components.

The setTomTomNavigation(TomTomNavigation) method has to be called first.

If you want to dispose the navigation you have to do it directly on the TomTomNavigation object.

tomTomNavigation.dispose()