User location

VERSION 0.3.34
PUBLIC PREVIEW

The TomTom Map Display module allows you to show the current user location on the map. Location data is provided by the LocationEngine and is used to display the user location marker indicator on the map. See how use the engine in the location guide.

Using the location engine with the map

Location updates are generated by the LocationEngine. To receive them you need to provide the LocationEngine object to the TomTomMap. It will be used by the map to position the location marker according to the position updates.

tomTomMap.setLocationEngine(locationEngine)

You can also use the TomTomMap object to retrieve currently used LocationEngine, access the latest user location, or check whether the location marker is visible on the screen.

Note that if the LocationEngine was not set, or did not provide any location data, the TomTomMap.currentLocation will not be returned.

1val mapLocationEngine = tomTomMap.getLocationEngine()
2val isLocationInVisibleArea = tomTomMap.isCurrentLocationInMapBoundingBox
3val currentLocation: GeoLocation? = tomTomMap.currentLocation

Location marker

The user location is shown as a location marker on the map. To show it, first create LocationMarkerOptions to configure the appearance of the marker.

1val locationMarkerOptions = LocationMarkerOptions(
2 type = LocationMarkerType.CHEVRON
3)

Then enable the location marker on the map. If a marker has already been set, the new one replaces it.

tomTomMap.enableLocationMarker(locationMarkerOptions)

You can also deactivate and remove a location marker that was previously added to the map.

tomTomMap.disableLocationMarker()

LocationMarkerOptions takes four parameters, which will be discussed below:

  • Location marker type
  • Marker magnification
  • Marker animation
  • Custom model

Only LocationMarkerType is required.

LocationMarkerType

This parameter specifies the type of the marker. It is required. The Map Display module provides two default markers:

Additionally, the LocationMarkerType.CUSTOM tells the map to use the custom marker provided to the LocationMarkerOptions class as a customModel property.

Marker magnification

The optional LocationMarkerOptions.markerMagnification property specifies the magnification level of the location marker:

  • Values between 0 and 1 will reduce the marker size.
  • A value of 1 keeps the marker at its original size.
  • Values greater than 1 will increase the marker size.

The value must be greater than 0 or the location marker will not be updated. This means that any marker that was previously set will not be changed, and if no marker was previously set the default pointer image will be used.

Animation speed

You can customize the speed of animations between location updates by setting the optional LocationMarkerOptions.animationDuration property. It represents the duration of animations between consecutive locations. By default it is set to null which is identified as autodetect. This enables the Map Display module to smoothly perform animation. Setting it to 0 results in turning off animation.

Custom location markers

The Map Display module supports using a custom image as the location marker. To do this, provide the path to the resource to the optional LocationMarkerOptions.customModel property. The only supported format is glTF (Graphics Language Transmission Format). Both extensions of it are allowed: gltf (text-based) and glb (binary-based).

The resources must be locally stored on the device. You can store them in assets - asset://, or in the file directory - file://.

The type of the location marker must be set to LocationMarkerType.Custom.

OnLocationMarkerClickListener

The Map Display module provides a listener that can be set to the map to report on click events performed on the location marker. If the user taps on the marker, the OnLocationMarkerClickListener provides the coordinates of the location on the map and the coordinates of the point touched on the screen. If the listener is no longer needed it can be removed.

1val onLocationMarkerClickListener =
2 OnLocationMarkerClickListener { point: Point, position: GeoCoordinate ->
3 /* YOUR CODE GOES HERE */
4 }
5tomTomMap.addOnLocationMarkerClickListener(onLocationMarkerClickListener)
6tomTomMap.removeOnLocationMarkerClickListener(onLocationMarkerClickListener)

Location accuracy

By default the received location is recognized as accurate if the accuracy is less than 50 meters. However, you can change it by setting the LocationAccuracyPolicy. This parameter takes the received GeoLocation as an input. The return value indicates if the location is accurate enough. If it returns true, the location is considered accurate.

1tomTomMap.locationAccuracyPolicy = LocationAccuracyPolicy { location: GeoLocation ->
2 location.accuracy ?: 0.0 < 100.0
3}