Markers

VERSION 2.1.2

Overview

The Marker composable displays a custom marker on a map. The Marker composable must be placed inside a map container: like the content block of TomTomMap. This ensures they’re properly attached to the map’s context.

See the Getting Started guide to add the TomTomMap to your app.

Displaying a marker

To display a marker, the first step is to create instances of MarkerData and MarkerProperties.

The essential property for MarkerData is:

geoPoint - The geographic location of the marker.

1val amsterdam = GeoPoint(52.379189, 4.899431)
2markerData = MarkerData(
3    geoPoint = amsterdam,
4)

The required properties for MarkerProperties are:

pinImage - The Image that will be used as a Marker pin.

1markerProperties = MarkerProperties(
2    pinImage = ImageFactory.fromResource(R.drawable.ic_marker_pin),
3)

Next, add the marker to the map using the defined MarkerData and MarkerProperties instances:

1TomTomMap(
  infrastructure = mapDisplayInfrastructure,
  modifier = modifier,
  state = mapViewState,
5) {
  Marker(
      data = markerData,
      properties = markerProperties,
  )
10}

The marker will be displayed at the provided geographic location. The Map SDK does not impose a limit on the number of markers added to the map. In order to reduce memory usage, the images used for markers are cached. > Note: The user’s device may have limited resources, which can reduce the performance of the application.

Styling

A custom image for the marker must be defined using the ImageFactory object. ImageFactory allows you to create images from a variety of sources:

Bitmap
Drawable from resources
Assets
URI

When you then create the MarkerProperties object you can specify its pinImage property which is the bottom layer of the marker and defines its boundaries. The background of the marker can be customized with the shieldImage property of MarkerProperties. The pinIconImage defines a layer used to display an icon on the pin. It will be placed over the background. Note that the pinIconImage will be rendered only within the boundaries of pinImage.

1val markerProperties = MarkerProperties(
2    pinImage = ImageFactory.fromResource(R.drawable.ic_marker_pin),
3) {
4    pinIconImage = ImageFactory.fromResource(R.drawable.ic_marker_icon)
5}
6TomTomMap(
7    infrastructure = mapDisplayInfrastructure,
8    modifier = modifier,
9    state = mapViewState,
10) {
11    Marker(
12        data = markerData,
13        properties = markerProperties,
14    )
15}

Example: the property is set to the orange marker pin, which is a background for the fork and knife icon set as pinIconImage.

Dynamic content

You can remove or hide a marker using the isVisible parameter of the Marker composable or control its presence in the composition based on a condition. Here’s how the visibility and removal works:

Hiding the marker

By setting the isVisible property of the Marker composable to false, the marker can be hidden. The marker remains part of the UI hierarchy but is simply not displayed.

1Marker(
2    data = markerData,
3    properties = markerProperties,
4    isVisible = true, // Marker is visible
5)

Control flow

To remove the marker entirely from the composition, you can use an if statement or a conditional. As standard in Compose UI, control flows can be used to control the content of the map.

1if (isVisible) {
  Marker(
      data = markerData,
      properties = markerProperties,
      state = rememberMarkerState(),
  )
7}

UI interaction

You can handle click and long-click events performed on markers by specifying the appropriate listeners in the Marker composable. Use onClick and onLongClick for handling the events.

1Marker(
  data = markerData,
  properties = markerProperties,
  onClick = {
      // Your code goes here
  },
7)

'onClick':

1Marker(
  data = markerData,
  properties = markerProperties,
  onClick = {
      // Your code goes here
  },
7)

'onLongClick':

1Marker(
  data = markerData,
  properties = markerProperties,
  onLongClick = {
      // Your code goes here
  },
7)

Showing and hiding balloons

Balloons are popup views that appear on top of the map when the user taps a marker. They do not appear by default.

To show balloons, use the MarkerState object on the Marker composable to manage the selection state of the marker. You can also display balloons with text content using the balloonText property of the MarkerProperties object. To achieve this, utilize the built-in BalloonViewAdapter.

1val markerState = rememberMarkerState()
2TomTomMap(
3    infrastructure = mapDisplayInfrastructure,
4    modifier = modifier,
5    state = mapViewState,
6) {
7    Marker(
8        data = markerData,
9        properties = markerProperties,
10        state = markerState,
11    )
12}
13markerState.select()

To hide a balloon, call state.deselect().

To check if a balloon is already visible, use the state.isSelected() method.

Multiple markers

You can also add multiple markers using the Markers composable.

1Markers(
  markers = listOf(
      MarkerEntry(
          data = MarkerData(
              geoPoint = GeoPoint(52.379189, 4.899431),
          ),
          properties = MarkerProperties(
              pinImage = ImageFactory.fromResource(R.drawable.ic_marker_pin),
          ),
      ),
      MarkerEntry(
          data = MarkerData(
              geoPoint = GeoPoint(51.379189, 5.899431),
          ),
          properties = MarkerProperties(
              pinImage = ImageFactory.fromResource(R.drawable.ic_cafe),
          ),
      ),
  ),
20)

The onClick parameter is applied to all markers in the list. It provides the corresponding MarkerId of the clicked marker to the lambda function.

Using MarkersState enables you to programmatically manage marker selection, deselection, and visibility.

The default state can be created using rememberMarkersState().

Next steps

Since you have learned how to show traffic on the map, here are recommendations for the next steps: