Map configuration

The Map Display module allows you to show the TomTom map in your Android application. To meet your use case requirements, you can apply initial settings during initialization using MapOptions or attributes. However, the map configuration can be also changed during runtime using the TomTomMap object.

Initializing the map in code

If the map is initialized in the Kotlin code, use the MapOptions object to provide initial configuration. Then when the map is displayed, all the settings will be already applied.

MapOptions properties are as follow:

Initializing the map in XML

If map initialization is performed in the layout file, the initial configuration can be set using attributes. The full list of attributes used to configure MapFragment is shown below. Each property can be mapped to the respective field in the MapOptions class. The same attributes can be applied to the MapView object.

1<androidx.fragment.app.FragmentContainerView xmlns:tomtom="http://schemas.android.com/apk/res-auto"
2    android:id="@+id/map_fragment"
3    android:name="com.tomtom.sdk.map.display.ui.MapFragment"
4    android:layout_width="match_parent"
5    android:layout_height="match_parent"
6    tomtom:mapKey="YOUR_TOMTOM_API_KEY"
7    tomtom:mapPaddingBottom="10"
8    tomtom:mapPaddingLeft="10"
9    tomtom:mapPaddingRight="10"
10    tomtom:mapPaddingTop="10"
11    tomtom:cameraTilt="45"
12    tomtom:cameraRotation="20"
13    tomtom:cameraPositionZoom="10"
14    tomtom:cameraPositionLatitude="52.379189"
15    tomtom:cameraPositionLongitude="4.899431"
16    tomtom:cameraBoundsTopLeftLatitude="52.379189"
17    tomtom:cameraBoundsTopLeftLongitude="4.899431"
18    tomtom:cameraBoundsBottomRightLatitude="51.89275"
19    tomtom:cameraBoundsBottomRightLongitude="5.67124"
20    tomtom:styleUri="http://path.to.your.style"
21    tomtom:styleDarkUri="http://path.to.your.dark.style"
22    tomtom:styleLayerMappingUri="http://path.to.your.style.layer.mapping"
23    tomtom:styleDarkLayerMappingUri="http://path.to.your.dark.style.layer.mapping"
24    tomtom:styleMode="Dark" />

Caching

Map caching can be configured using onlineCachePolicy, which you need to provide to the MapOptions object. The Map Display module caches:

• Map tiles.
• Styles.
• Sprites.
• Fonts.

Custom settings can be applied using the OnlineCachePolicy.Custom(Map<String, Duration>, Long) class. It requires two parameters:

• sizeLimit - Maximum size of the cache in bytes.

By default, the cache size limit is set to 10MB.

Caching can be influenced by the server, which can for example forbid caching.

Frame rate

By default, the map is rendered with a refresh rate of 60 FPS. You can change the frame rate, but note that the application will round the change to the nearest factor of 60 to ensure the new value will work with standard displays. This means that, for example, if you set the frame rate to 24 FPS, it will be rounded down to 20 FPS.

tomTomMap.setFrameRate(24)

MapView lifecycle

If you are using MapView directly, you have to handle its lifecycle changes. They are used to control the underlying map renderer. The following methods must be bound to your activity or fragment lifecycle:

1override fun onCreate(
2    savedInstanceState: Bundle?,
3    persistentState: PersistableBundle?,
4) {
5    super.onCreate(savedInstanceState, persistentState)
6    mapView.onCreate(savedInstanceState)
7}
8
9override fun onStart() {
10    super.onStart()
11    mapView.onStart()
12}
13
14override fun onResume() {
15    super.onResume()
16    mapView.onResume()
17}
18
19override fun onPause() {
20    super.onPause()
21    mapView.onPause()
22}
23
24override fun onStop() {
25    super.onStop()
26    mapView.onStop()
27}
28
29override fun onSaveInstanceState(outState: Bundle) {
30    super.onSaveInstanceState(outState)
31    mapView.onSaveInstanceState(outState)
32}
33
34override fun onDestroy() {
35    super.onDestroy()
36    mapView.onDestroy()
37}

If you are using MapView in a fragment, the MapView.onCreate(Bundle?) method should be called in the onCreateView(LayoutInflater, ViewGroup?, Bundle?).

If the configuration changes because of screen rotation the same map instance is rendered. This means that any operations made on the map, such as camera position, map style and markers, are preserved.

Next steps

Since you have learned how to configure a map, here are recommendations for the next steps:

• MapOptions in API reference
• Style the map
• Show current user location