Map configuration

VERSION 0.3.34
PUBLIC PREVIEW

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:

Property

required/optional

Description

mapKey

required

Maps API key.

cameraOptions

optional

CameraOptions for a map. Provides position, rotation, tilt and zoom of the camera.

padding

optional

Padding for a MapView. Set to 0 for all sides by default.

mapStyle

optional

Custom map style provided as StyleDescriptor. Read more about styling the map here.

styleMode

optional

Defines the StyleMode that will be used during initialization. Read more about styling the map here.

resourceCachePolicy

optional

Provides a custom ResourceCachePolicy that should be used for style caching. Used for map style file caching.

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.maps.display.ui.MapFragment"
4 android:layout_width="match_parent"
5 android:layout_height="match_parent"
6 tomtom:mapKey="YOUR_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 ResourceCachePolicy, which you need to provide to the MapOptions object. The Map Display module caches:

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

If there is no need to cache anything from the map, set the ResourceCachePolicy.NoCache object. Otherwise, custom settings can be applied using the ResourceCachePolicy.TimeToLive(Long, Duration) class. It requires two parameters:

  • sizeLimit - Maximum size of the cache in bytes.
  • maxAge - Maximum time that fetched resources can stay in the cache.

By default, the cache size limit is set to 100MB and the lifetime duration to 10 days.

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

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.