Developer

Navigation SDK application

VERSION 2.1.2

The Navigation SDK application is a simple yet complete application designed to demonstrate the usage of the core functionalities of the SDK, such as map display, location, search, routing and navigation. Its primary focus is to show developers how to leverage the SDK to build a fully functional navigation app while adhering to Jetpack Compose’s best practices.

Application structure

The entry point to this part of the app is the NavigationActivity, which serves as the main activity for the navigation example. This activity initializes the necessary components and sets up the MapScreen composable, which is the central UI component of the application.

1MapScreen(
2    settingsRepository = LocalSettingsRepository(dataStore),
3    modifier = Modifier.padding(innerPadding),
4    onCheckLocationPermission = onCheckLocationPermission,
5    locationRequestGrantedFlow = locationRequestGrantedFlow.asStateFlow(),
6    onSettingsClick = { startActivity(Intent(this, SettingsActivity::class.java)) },
7)

One screen, multiple scenarios

The Navigation SDK application is built around a single screen with multiple scenarios. The MapScreen.kt file is the heart of the application, managing different states and UI components based on the current scenario.

Each scenario represents a state of the navigation experience, and the flow follows this sequence except for the last one, Free Driving, that would be a separate flow that starts from Home automatically if the GPS detects the user is moving:

  • HOME: The initial state when the app starts, showing the map and allowing the user to search for locations.
  • POI_FOCUS: When a point of interest is selected and focused on the map.
  • ROUTE_PREVIEW: When a route is calculated and displayed before navigation starts.
  • GUIDANCE: When turn-by-turn navigation is active, guiding the user to their destination.
  • DESTINATION_ARRIVAL: When the user has arrived at their destination.
  • FREE_DRIVING: When the user is driving without a specific route, with the app tracking their location.

Each scenario has its own set of UI components and state holders, but they all share the same map view and underlying infrastructure.

Architecture components

The Navigation example app follows the MVVM (Model-View-ViewModel) architecture pattern, with some additional components to manage state and UI:

State holders

State holders are data classes that contain the state and callbacks for a specific scenario. For example, the HomeStateHolder contains the state for the home screen, including the user’s location, POI places, and callbacks for various actions:

1data class HomeStateHolder(
2    val locationUpdates: StateFlow<GeoPoint?>,
3    val poiPlaces: List<PlaceDetails>,
4    val recenterMapStateHolder: RecenterMapStateHolder,
5    val onAnimateCamera: (CameraOptions) -> Unit,
6    val searchStateHolder: SearchStateHolder,
7    val isDeviceInLandscape: Boolean,
8    val onSafeAreaTopPaddingUpdate: (Int) -> Unit,
9    val onSafeAreaBottomPaddingUpdate: (Int) -> Unit,
10    val onSettingsClick: () -> Unit,
11)

UI components

UI components are composable functions that use state holders to render the UI for a specific scenario. For example, the HomeUiComponents function renders the UI for the home screen using the HomeStateHolder:

1/**
2 * Displays the Home scenario UI with a search panel and recenter control, adapting layout for
3 * orientation and updating safe‑area insets as needed.
4 */
5@Composable
6fun BoxScope.HomeUiComponents(homeStateHolder: HomeStateHolder) {

View models

View models contain the business logic for the application and interact with the SDK APIs. They manage the state and provide methods to update it. The main view model is MapScreenViewModel, which manages the overall state of the map screen and dispatches actions to update it:

1/**
2 * Coordinates map screen state, location/camera control, POI data, route preview, and turn-by-turn guidance.
3 */
4class MapScreenViewModel(
5    sdkContext: SdkContext,
6    private val defaultLocationProvider: LocationProvider,
7    private val reverseGeocoder: ReverseGeocoder,
8    private val navigation: TomTomNavigation,
9    private val freeDrivingManager: FreeDrivingManager,
10    private val onClearMap: () -> Unit,
11    private val onCheckLocationPermission: () -> Boolean,
12    private val textToSpeechEngine: TextToSpeechEngine,
13) : ViewModel() {

The view models are responsible for interacting with the SDK APIs, such as routing, search, and navigation. They process the data from these APIs and update the state accordingly, which then flows down to the UI components through the state holders.

Start working with the Navigation SDK application

Once introduced to the Navigation SDK application it is time to start working with it:

  • Understand the overall structure: The app is built around the MapScreen composable, which manages different scenarios.
  • Explore the state holders: Each scenario has its own state holder that contains the state and callbacks.
  • Look at the UI components: Each scenario has its own UI components that render the UI based on the state.
  • Study the view models: The view models contain the business logic and interact with the SDK APIs.
  • Run the app and try different scenarios: The best way to understand the app is to run it and see how it transitions between different scenarios.

By understanding how the Navigation example app is structured and how it uses the SDK APIs and composables, you’ll be well-equipped to build your own navigation application using the Navigation SDK.

Next steps