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

1
tomtomMap.cameraPosition

Compose

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

Get Camera Tracking Mode

XML

1
tomtomMap.cameraTrackingMode

Compose

1
// TomTomMap's state
2
mapViewState.cameraState.trackingMode

Get Current Location

XML

1
tomtomMap.currentLocation

Compose

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

Is Current Location In Bounding Box

XML

1
tomtomMap.isCurrentLocationInMapBoundingBox

Compose

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

Is Gestures Enabled

XML

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

Compose

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

Primitive Operations

Add Marker

XML

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

Compose

1
TomTomMap(
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

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

Compose

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

Add Markers

XML

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

Compose

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

Markers APIs

XML

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

Compose

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

Add Polyline

XML

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

Compose

1
TomTomMap(
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

1
tomtomMap.hideHillShading()

Compose

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

Hide Traffic Flow

XML

1
tomtomMap.hideTrafficFlow()

Compose

1
trafficState.showTrafficFlow = false

Hide Traffic Incidents

XML

1
tomtomMap.hideTrafficIncidents()

Compose

1
trafficState.showTrafficIncidents = false

Hide Vehicle Restrictions

XML

1
tomtomMap.hideVehicleRestrictions()

Compose

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

Load Style

XML

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

Compose

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

Set Style Mode

XML

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

Compose

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

Event Listeners

Camera Steady Listener

XML

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

Compose

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

Location Marker Click Listener

XML

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

Compose

1
TomTomMap(
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

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

Compose

1
TomTomMap(
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

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

Compose

1
TomTomMap(
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

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

Compose

1
TomTomMap(
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

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

Compose

1
TomTomMap(
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

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

Compose

1
TomTomMap(
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

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

Compose

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

Move Camera

XML

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

Compose

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

Zoom To Markers

XML

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

Compose

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

Zoom To Routes

XML

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

Compose

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

Other Utilities

Change Gesture Exclusion

XML

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

Compose

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

Coordinate For Point

XML

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

Compose

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

Point For Coordinate

XML

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

Compose

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

Enable Location Marker

XML

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

Compose

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

Get Caption

XML

1
tomtomMap.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

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

Get Copyrights

XML

1
tomtomMap.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

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

Get Visible Region

XML

1
tomtomMap.getVisibleRegion()

Compose

1
// TomTomMap's state
2
mapViewState.getVisualRegion()

Set Frame Rate

XML

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

Compose

1
// TomTomMap's state
2
mapViewState.frameRate = frameRate

Set Language

XML

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

Compose

1
// TomTomMap's state
2
mapViewState.locale = locale

Set Padding

XML

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

Compose

1
// TomTomMap's state
2
mapViewState.safeArea = paddingValues

Update Vehicle

XML

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

Compose

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