Developer

Demo Examples

VERSION 2.1.2

The demos are smaller, focused showcases designed to demonstrate specific functionalities provided by the Navigation SDK. Each demo isolates a particular feature, making it easier to understand how to implement that functionality without the complexity of a full navigation app.

Demos structure

DemoActivity: The host for all demos

Each demo is hosted by a single activity, DemoActivity.kt, which serves as a container for the different demo screens. This activity:

  • Initializes the necessary components for all demos.
  • Shows a different demo according to the destination selected.
  • Provides a common infrastructure for error handling and UI state management.

The DemoActivity determines which demo to display based on the destination passed to it from the main activity:

1when (destination) {
2    is RoutePlanningDestination -> RoutePlanningScreen(demoViewModel = demoViewModel)
3    is EvSearchDestination -> EvSearchScreen(demoViewModel = demoViewModel)
4    is PoiAlongRouteDestination -> PoiAlongRouteScreen(demoViewModel = demoViewModel)
5    is AutocompleteDestination -> AutocompleteScreen(demoViewModel = demoViewModel)
6    is PoiSearchAreaDestination -> PoiSearchAreaScreen(demoViewModel = demoViewModel)
7    else -> {}
8}

DemoMap: The shared map component

One of the key components of the demo architecture is the DemoMap composable, which provides a consistent map display used across all demos. This component:

  • Encapsulates the Navigation SDK functionality.
  • Manages camera positioning and animations.
  • Handles map gestures and interactions.
  • Provides a content slot that can be customized by each demo.
1@Composable
2fun DemoMap(
3    mapUiState: DemoMapUiState,
4    mapDisplayInfrastructure: MapDisplayInfrastructure,
5    isDeviceInLandscape: Boolean,
6    modifier: Modifier = Modifier,
7    cameraOptions: CameraOptions? = null,
8    zoomToAllMarkers: Boolean = false,
9    disableGestures: Boolean = false,
10    mapViewState: MapViewState,
11    onMapReady: () -> Unit = { },
12    content:
13        @Composable
14        @TomTomMapComposable () -> Unit = { },
15) {
16    val localDensity = LocalDensity.current
17    mapViewState.safeArea = PaddingValues(
18        start = safeAreaStartPadding(isDeviceInLandscape),
19        bottom = localDensity.run { mapUiState.safeAreaBottomPadding.toDp() },
20        top = localDensity.run { mapUiState.safeAreaTopPadding.toDp() },
21    )
22

23    if (disableGestures) {
24        mapViewState.gestureState.config = GesturesConfig {
25            isScrollEnabled = false
26            isZoomEnabled = false
27        }
28    }
29

30    LaunchedEffect(zoomToAllMarkers) {
31        mapViewState.cameraState.zoomToAllMarkers(padding = MARKERS_ZOOM_PADDING_DP)
32    }
33

34    LaunchedEffect(cameraOptions) {
35        cameraOptions?.let { mapViewState.cameraState.animateCamera(it) }
36    }
37

38    TomTomMap(
39        modifier = modifier,
40        infrastructure = mapDisplayInfrastructure,
41        state = mapViewState,
42        onMapReady = onMapReady,
43        content = content,
44    )
45}

This shared component ensures consistency across demos while allowing each demo to customize the map display for its specific needs.

Demo implementation pattern

Each demo follows a consistent implementation pattern that makes them easy to understand and modify:

Screen and ViewModel architecture

Every demo consists of two main components:

  • Screen Component: A Jetpack Compose composable function that defines the UI for the demo.
  • ViewModel: A class that contains the business logic and state management for the demo.

For example, the PoiSearchAreaScreen composable defines the UI for the custom map style demo, while the PoiSearchAreaViewModel handles the logic for loading and applying map styles.

Demos

Routing demos

Route planning

In this Demo the app shows a planned route between London and Paris. The user can modify the route by selecting the Fastest, Shortest or Eco friendly route. Also the user can select to avoid Motorways, Toll roads or Ferries. Here is how to plan a route with customized Planning options:

1val routePlanningOptions = buildRoutePlanningOptions(
2    itinerary = Itinerary(PARIS, LONDON),
3    maxAlternatives = 2,
4    routeType = routeType.value,
5    avoids = getAvoids(),
6)
7routePlanJob = routePlanner.planRoute(
8    routePlanningOptions = routePlanningOptions,
9    object : RoutePlanningCallback {
10        override fun onSuccess(result: RoutePlanningResponse) {
11            onRoutePlanningSuccess(result)
12        }
13

14        override fun onFailure(failure: RoutingFailure) {
15            onRoutePlanningFailure(failure)
16        }
17    },
18)

Search demos

EV search

This demo shows how to search for EV charging stations filtering by charging speed, connector type, access type (e.g., public or private) or status (e.g., available or occupied). Here is the code for searching chargers according to the options selected by the user:

1performEvSearch(
2    searchApi = search,
3    evSearchOptions = buildEvSearchOptionsForNearbySearch(
4        geoBias = it,
5        init = {
6            radius = Distance.kilometers(EV_SEARCH_DEFAULT_RADIUS_KM)
7            minPower = powerFilter?.minPower
8            maxPower = powerFilter?.maxPower
9            connectors = connectorsFilter
10            status = statusFilter?.status
11            accessTypes = accessTypesFilter
12        },
13    ),
14)

Search POIs along the route

This demo shows how to search POIs along a planned route like hotels or restaurants. Here is the code to search for the category selected by the user with a maximum detour specified in the MAX_DETOUR_DURATION const:

1performSearch(
2    buildAlongRouteWithPoiCategorySearchOptions(
3        polyline = selectedRoute.routePoints.map { it.coordinate },
4        categoryIds = setOf(CategoryId(standardCategoryId)),
5        maxDetourDuration = MAX_DETOUR_DURATION.minutes,
6    ),
7)

Search POIs in a given area

This demo shows how to search POIs inside a given area. Here is the code to search for a given category:

1performSearch(
2    buildPoiCategorySearchOptions(
3        categoryIds = setOf(CategoryId(standardCategoryId)),
4        geoBias = it,
5    ),
6)

Search with Autocomplete options

This demo shows how to use Autocomplete suggestions in a search input and how to search for Categories, Brands or simple plain text. Here is the code to get Autocomplete suggestions while typing in characters in the search input:

1autocomplete(
2    buildAutocompleteOptions(
3        query = input,
4        geoBias = TOMTOM_AMSTERDAM_OFFICE,
5    ),
6)

In the response you get a list of AutocompleteSegments that could be Categories, Brands or Text. And with that segment, you can create the searchOptions:

1val searchOptions = when (segment) {
2    is AutocompleteSegmentBrand -> {
3        buildBrandSearchOptions(segment.brand, geoBias = TOMTOM_AMSTERDAM_OFFICE)
4    }
5

6    is AutocompleteSegmentPoiCategory -> {
7        buildPoiCategorySearchOptions(
8            categoryIds = setOf(segment.poiCategory.id),
9            geoBias = TOMTOM_AMSTERDAM_OFFICE,
10        )
11    }
12

13    is AutocompleteSegmentPlainText -> {
14        buildTextSearchOptions(segment.plainText, geoBias = TOMTOM_AMSTERDAM_OFFICE)
15    }
16

17    else -> null
18}
19

20searchOptions?.let {
21    performSearch(searchOptions = it, onSearchSuccess = onSearchSuccess, onSearchFailure = onSearchFailure)
22}

Start working with the demos

To start working with and understanding the demos:

  • Explore the demo categories: Begin by exploring the main categories of demos to get a sense of the available functionality. Each category showcases different aspects of the Navigation SDK.

  • Examine a specific demo: Choose a demo that interests you and examine its implementation:

    • Screen.kt - implements the UI structure.
    • ViewModel.kt - handles the integration with the Navigation SDK APIs.
    • DemoMap is a Composable function wrapping up all common configurations for TomTomMap shared among all demos.

    For example, if you’re interested in route planning, examine the RoutePlanningScreen.kt and RoutePlanningViewModel.kt files to understand how routes are calculated and displayed.

  • Understand the Navigation SDK integration: Pay attention to how each demo integrates with the SDK:

    • How it initializes and configures SDK components.
    • How it handles responses and errors from the SDK.
    • How it visualizes data from the SDK on the map.

Once understood how the demos work, you can start using them as a starting point for your own implementations!

Next steps