Developer

Events and gestures

VERSION 1.21.0

The map component provided by TomTom Map Display module reacts to different gestures with predefined behaviors, but this can be customized. By default the map supports the following gestures:

  • panning - moving one finger to drag the map.
  • zooming:
    • pinching to zoom in or out (scaling).
    • double-tapping to zoom in (scaling).
    • double-tapping and dragging to zoom in or out.
  • rotating - rotating two fingers around each other.
  • tilting - shoving (moving two fingers up or down on the map in parallel).

Listeners

The Map Display module provides a few map events that can be listened to by using the appropriate listeners.

Add the MapClickListener to the map by calling the addMapClickListener(MapClickListener) method on the TomTomMap object. Once the listener has been added, the onMapClicked method is triggered whenever the user taps on the map. The method supplies the coordinates for the point where the map was clicked. The method returns a boolean value indicating whether the listener has consumed the event. If the returned value is false the event is also passed to the underlying layers. Otherwise, the listeners of the next layers will not be triggered.

1tomtomMap.addMapClickListener { coordinate: GeoPoint ->
2    // YOUR CODE GOES HERE
3    return@addMapClickListener true
4}

The MapDoubleClickListener and MapLongClickListener listeners work in the same way. They also provide a method with coordinates as parameters and return a boolean to indicate if the event was consumed.

1tomtomMap.addMapDoubleClickListener { coordinate: GeoPoint ->
2    // YOUR CODE GOES HERE
3    return@addMapDoubleClickListener true
4}
5

6tomtomMap.addMapLongClickListener { coordinate: GeoPoint ->
7    // YOUR CODE GOES HERE
8    return@addMapLongClickListener true
9}

The last listener that can be set is MapPanningListener. It has 3 methods that report on panning actions:

1tomtomMap.addMapPanningListener(
2    object : MapPanningListener {
3        override fun onMapPanningEnded() {
4            // YOUR CODE GOES HERE
5        }
6

7        override fun onMapPanningOngoing() {
8            // YOUR CODE GOES HERE
9        }
10

11        override fun onMapPanningStarted() {
12            // YOUR CODE GOES HERE
13        }
14    },
15)

Remove existing listeners by calling the appropriate method and passing it a reference to the listener.

tomtomMap.removeMapClickListener(mapClickListener)

Removing other listeners is much the same. Pass a reference to the listener to be removed to the appropriate method:

Enabling / Disabling gestures

In the Map Display module, you can explicitly enable or disable specific gestures. To do so, set the appropriate flag on the TomTomMap object:

  • isRotationEnabled - determines whether rotation is enabled.
  • isZoomEnabled - determines whether zoom is enabled.
  • isScrollEnabled - determines whether panning is enabled.
  • isTiltEnabled - determines whether tilting is enabled.

Gesture Exclusions

The Map Display module includes functionality to choose circumstances where specific gestures are ignored. For example, if the map is being scaled (zoomed in or out), the user can’t pan it until the scaling is complete. To set a gesture exclusion, use the changeGestureExclusions(gesture: GestureType, exclusions: Set<GestureType>) method. The gesture parameter is the action whose behavior is restricted when gestures from the exclusion set are being performed.

For example: You can change the move gesture exclusions as follows:

tomtomMap.changeGestureExclusions(GestureType.Move, setOf(GestureType.Scale))

Then when you start scaling the map, panning it is disabled. The Map Display module uses the following default configuration for gesture exclusion:

  • Tilting excludes rotating, scaling and quick scaling.
  • Rotating excludes tilting, scaling and quick scaling.
  • Scaling excludes tilting and quick scaling.
  • Quick scaling excludes shove and scaling.
  • Moving excludes tilting and quick scaling.
  • Long pressing excludes rotation, scaling, quick scaling, tilting, and double tapping.
  • Double tapping excludes scaling and quick scaling.

You can also lift all restrictions for a specific GestureType by giving it an empty exclusion set.

tomtomMap.changeGestureExclusions(GestureType.Move, setOf())

Next steps

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