Developer

Migration guide

VERSION 2.1.2

This guide is designed to assist developers in migrating from XML layouts that utilize MapView and MapFragment to modern Jetpack Compose approach. It includes a comprehensive cheat sheet that outlines the key differences and advantages of using the TomTomMap APIs within a Compose environment compared to legacy implementations.

This section assumes that you have already reviewed the previous guides and have a foundational understanding of Jetpack Compose.

Members

Get Camera Position

XML

tomtomMap.cameraPosition

Compose

// TomTomMap's state
mapViewState.cameraState.data?.position

Get Camera Tracking Mode

XML

tomtomMap.cameraTrackingMode

Compose

// TomTomMap's state
mapViewState.cameraState.trackingMode

Get Current Location

XML

tomtomMap.currentLocation

Compose

// TomTomMap's state
mapViewState.locationState.getCurrentLocation()

Is Current Location In Bounding Box

XML

tomtomMap.isCurrentLocationInMapBoundingBox

Compose

// TomTomMap's state
mapViewState.locationState.isCurrentLocationInMapBoundingBox()

Is Gestures Enabled

XML

1tomtomMap.isMultiPointerPanEnabled
2tomtomMap.isRotationEnabled
3tomtomMap.isScrollEnabled
4tomtomMap.isTiltEnabled
5tomtomMap.isZoomEnabled

Compose

1// TomTomMap's state
2mapViewState.gestureState.config.isMultiPointerPanEnabled
3mapViewState.gestureState.config.isRotationEnabled
4mapViewState.gestureState.config.isScrollEnabled
5mapViewState.gestureState.config.isTiltEnabled
6mapViewState.gestureState.config.isZoomEnabled

Primitive Operations

Add Marker

XML

1val marker = tomtomMap.addMarker(
2    options = markerOptions,
3)

Compose

1TomTomMap(
2    infrastructure = viewModel.mapDisplayInfrastructure,
3    state = mapViewState,
4) {
5    Marker(
6        state = markerState,
7        data = MarkerData(geoPoint = MARKER_GEOPOINT),
8        properties = MarkerProperties(pinImage = PIN_IMAGE),
9    )
10}

Marker APIs

XML

1marker.select()
2marker.deselect()
3marker.isSelected()

Compose

1markerState.select()
2markerState.deselect()
3markerState.isSelected()

Add Markers

XML

1val markers = tomtomMap.addMarkers(
2    options = markersOptions,
3)

Compose

1private val listOfMarkers = listOf(
2    MarkerEntry(
3        markerId = firstMarkerId,
4        data = MarkerData(geoPoint = MARKER_GEOPOINT),
5        properties = MarkerProperties(pinImage = PIN_IMAGE),
6    ),
7)
8TomTomMap(
9    infrastructure = viewModel.mapDisplayInfrastructure,
10    state = mapViewState,
11) {
12    Markers(
13        state = markersState,
14        markers = listOfMarkers,
15    )
16}

Markers APIs

XML

1markers.firstOrNull()?.select()
2markers.firstOrNull()?.deselect()
3markers.firstOrNull()?.isSelected()

Compose

1markersState.selectMarker(firstMarkerId)
2markersState.deselectMarker(firstMarkerId)
3markersState.isMarkerSelected(firstMarkerId)

Add Polyline

XML

1tomtomMap.addPolyline(
2    options = polylineOptions,
3)

Compose

1TomTomMap(
2    infrastructure = viewModel.mapDisplayInfrastructure,
3    state = mapViewState,
4) {
5    Polyline(
6        data = PolylineData(
7            geoPoints = listOf(GEOPOINT, GEOPOINT_2),
8        ),
9    )
10}

Style Operations

Hide Hill Shading

XML

tomtomMap.hideHillShading()

Compose

// TomTomMap's state
mapViewState.styleState.showHillShading = false

Hide Traffic Flow

XML

tomtomMap.hideTrafficFlow()

Compose

trafficState.showTrafficFlow = false

Hide Traffic Incidents

XML

tomtomMap.hideTrafficIncidents()

Compose

trafficState.showTrafficIncidents = false

Hide Vehicle Restrictions

XML

tomtomMap.hideVehicleRestrictions()

Compose

// TomTomMap's state
mapViewState.styleState.showVehicleRestrictions = false

Load Style

XML

1tomtomMap.loadStyle(
2    style = StandardStyles.TomTomOrbisMaps.BROWSING,
3    callback = styleLoadingCallback,
4)

Compose

1// TomTomMap's state
2mapViewState.styleState.loadStyle(
3    style = StandardStyles.TomTomOrbisMaps.BROWSING,
4)

Set Style Mode

XML

1tomtomMap.setStyleMode(
2    mode = StyleMode.DARK,
3)

Compose

// TomTomMap's state
mapViewState.styleState.styleMode = StyleMode.DARK

Event Listeners

Camera Steady Listener

XML

1tomtomMap.addCameraSteadyListener {
2    println("Camera steady event occurred")
3}

Compose

// TomTomMap's state
mapViewState.cameraState.data?.isStable

Location Marker Click Listener

XML

1tomtomMap.addLocationMarkerClickListener { point: Point, geoPoint: GeoPoint ->
2    println("Clicked at geoPoint: $geoPoint, screen: $point")
3}

Compose

1TomTomMap(
2    infrastructure = viewModel.mapDisplayInfrastructure,
3    state = mapViewState,
4) {
5    CurrentLocationMarker(
6        onClick = { offset: Offset, geoPoint: GeoPoint ->
7            println("Clicked at geoPoint: $geoPoint, screen: $offset")
8        },
9    )
10}

Map Gestures Listeners

XML

1tomtomMap.addMapClickListener { geoPoint: GeoPoint ->
2    println("Map clicked at: $geoPoint")
3    true
4}
5tomtomMap.addMapDoubleClickListener { geoPoint: GeoPoint ->
6    println("Map double clicked at: $geoPoint")
7    true
8}
9tomtomMap.addMapLongClickListener { geoPoint: GeoPoint ->
10    println("Map long clicked at: $geoPoint")
11    true
12}
13tomtomMap.addMapPanningListener(
14    listener = mapPanningListener,
15)

Compose

1TomTomMap(
2    infrastructure = viewModel.mapDisplayInfrastructure,
3    state = mapViewState,
4    onMapClick = { geoPoint: GeoPoint ->
5        println("Map clicked at: $geoPoint")
6    },
7    onMapDoubleClickListener = { geoPoint: GeoPoint ->
8        println("Map double clicked at: $geoPoint")
9    },
10    onMapLongClick = { geoPoint: GeoPoint ->
11        println("Map long clicked at: $geoPoint")
12    },
13    onMapPanningListener = {
14        println("Map panning event occurred")
15    },

Marker Click Listener

XML

1tomtomMap.addMarkerClickListener { marker: Marker ->
2    println("Marker click event occurred for: $marker")
3}

Compose

1TomTomMap(
2    infrastructure = viewModel.mapDisplayInfrastructure,
3    state = mapViewState,
4) {
5    Marker(
6        state = markerState,
7        data = MarkerData(geoPoint = MARKER_GEOPOINT),
8        properties = MarkerProperties(pinImage = PIN_IMAGE),
9        onClick = {
10            println("Marker click event occurred")
11        },
12    )
13}

Marker Long Click Listener

XML

1tomtomMap.addMarkerLongClickListener { marker: Marker ->
2    println("Marker long click event occurred for: $marker")
3}

Compose

1TomTomMap(
2    infrastructure = viewModel.mapDisplayInfrastructure,
3    state = mapViewState,
4) {
5    Marker(
6        state = markerState,
7        data = MarkerData(geoPoint = MARKER_GEOPOINT),
8        properties = MarkerProperties(pinImage = PIN_IMAGE),
9        onLongClick = {
10            println("Marker long click event occurred")
11        },
12    )
13}

Polyline Click Listener

XML

1tomtomMap.addPolylineClickListener { polyline: Polyline ->
2    println("Polyline click event occurred for: $polyline")
3}

Compose

1TomTomMap(
2    infrastructure = viewModel.mapDisplayInfrastructure,
3    state = mapViewState,
4) {
5    Polyline(
6        data = PolylineData(
7            geoPoints = listOf(GEOPOINT, GEOPOINT_2),
8        ),
9        onClick = {
10            println("Polyline click event occurred")
11        },
12    )
13}

Traffic Incident Click Listener

XML

1tomtomMap.addTrafficIncidentClickListener { trafficIncidents: List<TrafficIncident>, geoPoint: GeoPoint ->
2    println("Clicked traffic incidents at $geoPoint: $trafficIncidents")
3}

Compose

1TomTomMap(
2    infrastructure = viewModel.mapDisplayInfrastructure,
3    state = mapViewState,
4) {
5    Traffic(
6        onTrafficIncidentClick = { trafficIncidents: List<TrafficIncident>, geoPoint: GeoPoint ->
7            println("Clicked traffic incidents at $geoPoint: $trafficIncidents")
8        },
9    )
10}

Camera Operations

Animate Camera

XML

1tomtomMap.animateCamera(
2    options = cameraOptions,
3)

Compose

1// TomTomMap's state
2mapViewState.cameraState.animateCamera(
3    cameraOptions = cameraOptions,
4)

Move Camera

XML

1tomtomMap.moveCamera(
2    options = cameraOptions,
3)

Compose

1// TomTomMap's state
2mapViewState.cameraState.moveCamera(
3    cameraOptions = cameraOptions,
4)

Zoom To Markers

XML

1tomtomMap.zoomToMarkers(
2    markers = markers,
3    padding = padding,
4)

Compose

1// TomTomMap's state
2mapViewState.cameraState.zoomToMarkers(
3    markersIds = markersIds,
4    padding = padding,
5)

Zoom To Routes

XML

1tomtomMap.zoomToRoutes(
2    padding = padding,
3)

Compose

1// TomTomMap's state
2mapViewState.cameraState.zoomToAllRoutes(
3    padding = padding,
4)

Other Utilities

Change Gesture Exclusion

XML

1tomtomMap.changeGestureExclusions(
2    gesture = GestureType.Move,
3    exclusions = setOf(GestureType.Scale),
4)

Compose

1// TomTomMap's state
2mapViewState.gestureState.config = GesturesConfig {
3    exclusions = mapOf(
4        GestureType.Move to setOf(GestureType.Scale),
5    )
6}

Coordinate For Point

XML

1tomtomMap.coordinateForPoint(
2    point = POINT,
3)

Compose

1// TomTomMap's state
2mapViewState.getGeoPointForOffset(
3    offset = offset,
4)

Point For Coordinate

XML

1tomtomMap.pointForCoordinate(
2    coordinate = COORDINATE,
3)

Compose

1// TomTomMap's state
2mapViewState.getScreenOffsetForGeoPoint(
3    geoPoint = geoPoint,
4)

Enable Location Marker

XML

1tomtomMap.enableLocationMarker(
2    LocationMarkerOptions(
3        type = LocationMarkerOptions.Type.Chevron,
4    ),
5)

Compose

1TomTomMap(
2    infrastructure = viewModel.mapDisplayInfrastructure,
3    state = mapViewState,
4) {
5    CurrentLocationMarker(
6        properties = CurrentLocationMarkerProperties {
7            type = LocationMarkerOptions.Type.Chevron
8        },
9    )
10}

Get Caption

XML

1tomtomMap.getCaption(
2    object : CopyrightsFetchingCallback {
3        override fun onSuccess(result: String) {
4            println("Caption: $result")
5        }
6

7        override fun onFailure(failure: CopyrightsFetchingFailure) {
8            println("Failure: $failure")
9        }
10    },
11)

Compose

// TomTomMap's state
mapViewState.copyrightsState.getCaption()

Get Copyrights

XML

1tomtomMap.getCopyrights(
2    object : CopyrightsFetchingCallback {
3        override fun onSuccess(result: String) {
4            println("Copyrights: $result")
5        }
6

7        override fun onFailure(failure: CopyrightsFetchingFailure) {
8            println("Failure: $failure")
9        }
10    },
11)

Compose

// TomTomMap's state
mapViewState.copyrightsState.getCopyrights()

Get Visible Region

XML

tomtomMap.getVisibleRegion()

Compose

// TomTomMap's state
mapViewState.getVisualRegion()

Set Frame Rate

XML

1tomtomMap.setFrameRate(
2    frameRate = frameRate,
3)

Compose

// TomTomMap's state
mapViewState.frameRate = frameRate

Set Language

XML

1tomtomMap.setLanguage(
2    language = locale,
3)

Compose

// TomTomMap's state
mapViewState.locale = locale

Set Padding

XML

1tomtomMap.setPadding(
2    padding = padding,
3)

Compose

// TomTomMap's state
mapViewState.safeArea = paddingValues

Update Vehicle

XML

1tomtomMap.updateVehicle(
2    vehicle = Vehicle.Car(),
3)

Compose

1// TomTomMap's infrastructure
2mapDisplayInfrastructure = mapDisplayInfrastructure.copy {
3    vehicle = Vehicle.Car()
4}