Migration guide

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 composable within a Compose environment compared to legacy implementations.

Two different types share the name TomTomMap. The composable used throughout this guide is com.tomtom.sdk.map.display.compose.TomTomMap, while the legacy class used with MapView and MapFragment is com.tomtom.sdk.map.display.TomTomMap.

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

tomtomMap.isMultiPointerPanEnabled
tomtomMap.isRotationEnabled
tomtomMap.isScrollEnabled
tomtomMap.isTiltEnabled
tomtomMap.isZoomEnabled

Compose

// TomTomMap's state
mapViewState.gestureState.config.isMultiPointerPanEnabled
mapViewState.gestureState.config.isRotationEnabled
mapViewState.gestureState.config.isScrollEnabled
mapViewState.gestureState.config.isTiltEnabled
mapViewState.gestureState.config.isZoomEnabled

Primitive Operations

Add Marker

XML

val marker = tomtomMap.addMarker(
options = markerOptions,
)

Compose

TomTomMap(
infrastructure = viewModel.mapDisplayInfrastructure,
state = mapViewState,
) {
Marker(
state = markerState,
data = MarkerData(geoPoint = MARKER_GEOPOINT),
properties = MarkerProperties(pinImage = PIN_IMAGE),
)
}

Marker APIs

XML

marker.select()
marker.deselect()
marker.isSelected()

Compose

markerState.select()
markerState.deselect()
markerState.isSelected()

Add Markers

XML

val markers = tomtomMap.addMarkers(
options = markersOptions,
)

Compose

private val listOfMarkers = listOf(
MarkerEntry(
markerId = firstMarkerId,
data = MarkerData(geoPoint = MARKER_GEOPOINT),
properties = MarkerProperties(pinImage = PIN_IMAGE),
),
)
TomTomMap(
infrastructure = viewModel.mapDisplayInfrastructure,
state = mapViewState,
) {
Markers(
state = markersState,
markers = listOfMarkers,
)
}

Markers APIs

XML

markers.firstOrNull()?.select()
markers.firstOrNull()?.deselect()
markers.firstOrNull()?.isSelected()

Compose

markersState.selectMarker(firstMarkerId)
markersState.deselectMarker(firstMarkerId)
markersState.isMarkerSelected(firstMarkerId)

Add Polyline

XML

tomtomMap.addPolyline(
options = polylineOptions,
)

Compose

TomTomMap(
infrastructure = viewModel.mapDisplayInfrastructure,
state = mapViewState,
) {
Polyline(
data = PolylineData(
geoPoints = listOf(GEOPOINT, GEOPOINT_2),
),
)
}

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

tomtomMap.loadStyle(
style = StandardStyles.TomTomOrbisMaps.BROWSING,
callback = styleLoadingCallback,
)

Compose

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

Set Style Mode

XML

tomtomMap.setStyleMode(
mode = StyleMode.DARK,
)

Compose

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

Event Listeners

Camera Steady Listener

XML

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

Compose

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

Location Marker Click Listener

XML

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

Compose

TomTomMap(
infrastructure = viewModel.mapDisplayInfrastructure,
state = mapViewState,
) {
CurrentLocationMarker(
onClick = { offset: Offset, geoPoint: GeoPoint ->
println("Clicked at geoPoint: $geoPoint, screen: $offset")
},
)
}

Map Gestures Listeners

XML

tomtomMap.addMapClickListener { geoPoint: GeoPoint ->
println("Map clicked at: $geoPoint")
true
}
tomtomMap.addMapDoubleClickListener { geoPoint: GeoPoint ->
println("Map double clicked at: $geoPoint")
true
}
tomtomMap.addMapLongClickListener { geoPoint: GeoPoint ->
println("Map long clicked at: $geoPoint")
true
}
tomtomMap.addMapPanningListener(
listener = mapPanningListener,
)

Compose

TomTomMap(
infrastructure = viewModel.mapDisplayInfrastructure,
state = mapViewState,
onMapClick = { geoPoint: GeoPoint ->
println("Map clicked at: $geoPoint")
},
onMapDoubleClickListener = { geoPoint: GeoPoint ->
println("Map double clicked at: $geoPoint")
},
onMapLongClick = { geoPoint: GeoPoint ->
println("Map long clicked at: $geoPoint")
},
onMapPanningListener = {
println("Map panning event occurred")
},

Marker Click Listener

XML

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

Compose

TomTomMap(
infrastructure = viewModel.mapDisplayInfrastructure,
state = mapViewState,
) {
Marker(
state = markerState,
data = MarkerData(geoPoint = MARKER_GEOPOINT),
properties = MarkerProperties(pinImage = PIN_IMAGE),
onClick = {
println("Marker click event occurred")
},
)
}

Marker Long Click Listener

XML

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

Compose

TomTomMap(
infrastructure = viewModel.mapDisplayInfrastructure,
state = mapViewState,
) {
Marker(
state = markerState,
data = MarkerData(geoPoint = MARKER_GEOPOINT),
properties = MarkerProperties(pinImage = PIN_IMAGE),
onLongClick = {
println("Marker long click event occurred")
},
)
}

Polyline Click Listener

XML

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

Compose

TomTomMap(
infrastructure = viewModel.mapDisplayInfrastructure,
state = mapViewState,
) {
Polyline(
data = PolylineData(
geoPoints = listOf(GEOPOINT, GEOPOINT_2),
),
onClick = {
println("Polyline click event occurred")
},
)
}

Traffic Incident Click Listener

XML

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

Compose

TomTomMap(
infrastructure = viewModel.mapDisplayInfrastructure,
state = mapViewState,
) {
Traffic(
onTrafficIncidentClick = { trafficIncidents: List<TrafficIncident>, geoPoint: GeoPoint ->
println("Clicked traffic incidents at $geoPoint: $trafficIncidents")
},
)
}

Camera Operations

Animate Camera

XML

tomtomMap.animateCamera(
options = cameraOptions,
)

Compose

// TomTomMap's state
mapViewState.cameraState.animateCamera(
cameraOptions = cameraOptions,
)

Move Camera

XML

tomtomMap.moveCamera(
options = cameraOptions,
)

Compose

// TomTomMap's state
mapViewState.cameraState.moveCamera(
cameraOptions = cameraOptions,
)

Zoom To Markers

XML

tomtomMap.zoomToMarkers(
markers = markers,
padding = padding,
)

Compose

// TomTomMap's state
mapViewState.cameraState.zoomToMarkers(
markersIds = markersIds,
padding = padding,
)

Zoom To Routes

XML

tomtomMap.zoomToRoutes(
padding = padding,
)

Compose

// TomTomMap's state
mapViewState.cameraState.zoomToAllRoutes(
padding = padding,
)

Other Utilities

Change Gesture Exclusion

XML

tomtomMap.changeGestureExclusions(
gesture = GestureType.Move,
exclusions = setOf(GestureType.Scale),
)

Compose

// TomTomMap's state
mapViewState.gestureState.config = GesturesConfig {
exclusions = mapOf(
GestureType.Move to setOf(GestureType.Scale),
)
}

Coordinate For Point

XML

tomtomMap.coordinateForPoint(
point = POINT,
)

Compose

// TomTomMap's state
mapViewState.getGeoPointForOffset(
offset = offset,
)

Point For Coordinate

XML

tomtomMap.pointForCoordinate(
coordinate = COORDINATE,
)

Compose

// TomTomMap's state
mapViewState.getScreenOffsetForGeoPoint(
geoPoint = geoPoint,
)

Enable Location Marker

XML

tomtomMap.enableLocationMarker(
LocationMarkerOptions(
type = LocationMarkerOptions.Type.Chevron,
),
)

Compose

TomTomMap(
infrastructure = viewModel.mapDisplayInfrastructure,
state = mapViewState,
) {
CurrentLocationMarker(
properties = CurrentLocationMarkerProperties {
type = LocationMarkerOptions.Type.Chevron
},
)
}

Get Caption

XML

tomtomMap.getCaption(
object : CopyrightsFetchingCallback {
override fun onSuccess(result: String) {
println("Caption: $result")
}
override fun onFailure(failure: CopyrightsFetchingFailure) {
println("Failure: $failure")
}
},
)

Compose

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

Get Copyrights

XML

tomtomMap.getCopyrights(
object : CopyrightsFetchingCallback {
override fun onSuccess(result: String) {
println("Copyrights: $result")
}
override fun onFailure(failure: CopyrightsFetchingFailure) {
println("Failure: $failure")
}
},
)

Compose

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

Get Visible Region

XML

tomtomMap.getVisibleRegion()

Compose

// TomTomMap's state
mapViewState.getVisualRegion()

Set Frame Rate

XML

tomtomMap.setFrameRate(
frameRate = frameRate,
)

Compose

// TomTomMap's state
mapViewState.frameRate = frameRate

Set Language

XML

tomtomMap.setLanguage(
language = locale,
)

Compose

// TomTomMap's state
mapViewState.locale = locale

Set Padding

XML

tomtomMap.setPadding(
padding = padding,
)

Compose

// TomTomMap's state
mapViewState.safeArea = paddingValues

Update Vehicle

XML

tomtomMap.updateVehicle(
vehicle = Vehicle.Car(),
)

Compose

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