Interact with the map

_|

The Maps SDK for Android map view natively supports common gestures like pinch and double-tap for zooming. The table below outlines the available gestures and their default behaviors on the map.

Gesture	Description
Tap	Tap the screen with one finger. This gesture does not have a predefined map action.
Double Tap	To zoom the map in by a fixed amount, tap the screen twice with one finger.
Long Press	Press and hold one finger to the screen. This gesture does not have a predefined map action.
Pan	To move the map, press and hold one finger to the screen, and move it in any direction. The map will keep moving with a little momentum after the finger was lifted.
2 Finger Pan / Shove	To tilt the map, press and hold two fingers to the screen, and move them vertically. No behavior is predefined for other directions.
2 Finger Tap	To align map towards north, tap the screen with two fingers.
Pinch	To zoom in or out continuously, press and hold two fingers to the screen, and increase or decrease the distance between them. To rotate the map continuously, press and hold two fingers to the screen, and change the angle between them either by rotating them both or by moving one of them.

The SDK provides support in MapView, for informing whenever the user performs an action that could be detected. Usually, you will want to add a specific behavior to your application after a gesture was detected, like performing a selection after a tap on map.

• Tap: onTouch
• Double Tap (one finger taps the same area in quick succession): onDoubleTouch
• Two Taps (two fingers tap the screen simultaneously): onTwoTouches
• Long Press: onLongDown
• Pan: onMove obtains the two points between which the movement occurred.
• Shove: onShove obtains the angle, and gesture specific points
• Rotate: onMapAngleUpdated
• Fling: onSwipe
• Pinch: onPinch

The user can also listen for composite gestures:

• Tap followed by a pan: onTouchMove
• Pinch followed by a swipe: onPinchSwipe
• Tap followed by a pinch: onTouchPinch
• Two double touches: onTwoDoubleTouches

danger

Keep in mind that only one listener can be active at a time for a specific gesture. If multiple listeners are registered, only the most recently set listener will be invoked when the gesture is detected.

Use isCameraMoving() to check if the map camera is currently moving.

Enable and disable gestures

Touch gestures can be disabled or enabled by calling enableTouchGestures method like so:

Kotlin

// Get MapView from GemSurfaceView
val gemSurfaceView = findViewById<GemSurfaceView>(R.id.gem_surface)
val mapView = gemSurfaceView.mapView

mapView?.preferences?.enableTouchGestures(
    ETouchGestures.OnTouch.value or ETouchGestures.OnMove.value,
    false
)

Java

// Get MapView from GemSurfaceView
GemSurfaceView gemSurfaceView = findViewById(R.id.gem_surface);
MapView mapView = gemSurfaceView.getMapView();

if (mapView != null && mapView.getPreferences() != null) {
    mapView.getPreferences().enableTouchGestures(
        ETouchGestures.OnTouch.getValue() | ETouchGestures.OnMove.getValue(),
        false
    );
}

info

The desired gestures in the ETouchGestures enum can be enabled or disabled by setting the enabled parameter to true or false, respectively. By default, all gestures are enabled.

The ETouchGestures enum supports the following gesture types:

• Basic Touch: OnTouch, OnLongDown, OnDoubleTouch, OnTwoPointersTouch, OnTwoPointersDoubleTouch
• Movement: OnMove, OnTouchMove, OnSwipe
• Pinch and Rotation: OnPinchSwipe, OnPinch, OnRotate, OnShove
• Combined Gestures: OnTouchPinch, OnTouchRotate, OnTouchShove, OnRotatingSwipe

For checking if a gesture is enabled, the isTouchGestureEnabled method can be used:

Kotlin

// Get MapView from GemSurfaceView
val gemSurfaceView = findViewById<GemSurfaceView>(R.id.gem_surface)
val mapView = gemSurfaceView.mapView

val isTouchEnabled = mapView?.preferences?.isTouchGestureEnabled(ETouchGestures.OnTouch) ?: false

Java

// Get MapView from GemSurfaceView
GemSurfaceView gemSurfaceView = findViewById(R.id.gem_surface);
MapView mapView = gemSurfaceView.getMapView();

boolean isTouchEnabled = mapView != null && mapView.getPreferences() != null ? mapView.getPreferences().isTouchGestureEnabled(ETouchGestures.OnTouch) : false;

Implement gesture listeners

Let's see an example of how gesture listeners can be registered. The MapView provides specific listeners for each gesture. As soon as you register a listener, it will receive all related events for that gesture via the dedicated callback.

Kotlin

// Get MapView from GemSurfaceView
val gemSurfaceView = findViewById<GemSurfaceView>(R.id.gem_surface)
val mapView = gemSurfaceView.mapView

// Set up gesture listeners
mapView?.onMapAngleUpdated = { angle ->
    Log.d("Gesture", "onMapAngleUpdated: $angle")
}

mapView?.onTouch = { point ->
    Log.d("Gesture", "onTouch: $point")
}

mapView?.onMove = { start, end ->
    Log.d("Gesture", "onMove from (${start.x}, ${start.y}) to (${end.x}, ${end.y})")
}

mapView?.onLongDown = { point ->
    Log.d("Gesture", "onLongDown: $point")
}

Java

// Get MapView from GemSurfaceView
GemSurfaceView gemSurfaceView = findViewById(R.id.gem_surface);
MapView mapView = gemSurfaceView.getMapView();

// Set up gesture listeners
if (mapView != null) {
    mapView.setOnMapAngleUpdated(angle -> {
        Log.d("Gesture", "onMapAngleUpdated: " + angle);
    });

    mapView.setOnTouch(point -> {
        Log.d("Gesture", "onTouch: " + point);
    });

    mapView.setOnMove((start, end) -> {
        Log.d("Gesture", "onMove from (" + start.x + ", " + start.y + ") to (" + end.x + ", " + end.y + ")");
    });

    mapView.setOnLongDown(point -> {
        Log.d("Gesture", "onLongDown: " + point);
    });
}

danger

Executing resource-intensive tasks within map-related callbacks can degrade performance.

Implement map render listeners

The onViewportResized listener allows you to monitor when the map's viewport dimensions change. This can occur when the user resizes the application window or changes the orientation of the device. In this callback, you receive a Rect object representing the new viewport size.

Kotlin

mapView?.onViewportResized = { rect ->
    Log.d("Viewport", "Viewport resized to: ${rect.width}x${rect.height}")
}

Java

if (mapView != null) {
    mapView.setOnViewportResized(rect -> {
        Log.d("Viewport", "Viewport resized to: " + rect.getWidth() + "x" + rect.getHeight());
    });
}

Use cases include:

• Adjusting overlays or UI elements to fit the new viewport size.
• Triggering animations or updates based on the map's dimensions.

The onViewRendered listener is triggered after the map completes a rendering cycle. This listener provides EViewDataTransitionStatus and EViewCameraTransitionStatus parameters containing details about the rendering process.

Kotlin

mapView?.onViewRendered = { dataStatus, cameraStatus ->
    Log.d("Render", "View rendered - Data: $dataStatus, Camera: $cameraStatus")
}

Java

if (mapView != null) {
    mapView.setOnViewRendered((dataStatus, cameraStatus) -> {
        Log.d("Render", "View rendered - Data: " + dataStatus + ", Camera: " + cameraStatus);
    });
}

Map selection functionality

After detecting a gesture, such as a tap, usually some specific action like selecting a landmark or a route is performed on the MapView. This selection is made using a map cursor, which is invisible by default. To showcase its functionality, the cursor can be made visible using the MapViewPreferences setting:

Kotlin

// Get MapView from GemSurfaceView
val gemSurfaceView = findViewById<GemSurfaceView>(R.id.gem_surface)
val mapView = gemSurfaceView.mapView

// Enable cursor (default is false)
mapView?.preferences?.enableCursor = true
// Enable cursor to render on screen
mapView?.preferences?.enableCursorRender = true

Java

// Get MapView from GemSurfaceView
GemSurfaceView gemSurfaceView = findViewById(R.id.gem_surface);
MapView mapView = gemSurfaceView.getMapView();

// Enable cursor (default is false)
if (mapView != null && mapView.getPreferences() != null) {
    mapView.getPreferences().setEnableCursor(true);
    // Enable cursor to render on screen
    mapView.getPreferences().setEnableCursorRender(true);
}

Doing this will result in a crosshair-like icon in center of screen.

Displaying a cursor

Landmark selection

To get the selected landmarks, you can use the following code:

Kotlin

// Get MapView from GemSurfaceView
val gemSurfaceView = findViewById<GemSurfaceView>(R.id.gem_surface)
val mapView = gemSurfaceView.mapView

mapView?.onTouch = { pos ->
    // Set the cursor position
    mapView.cursorScreenPosition = pos

    // Get the landmarks at the cursor position
    val landmarks = mapView.cursorSelectionLandmarks

    landmarks?.forEach { landmark ->
        // handle landmark
        Log.d("Selection", "Selected landmark: ${landmark.name}")
    }
}

Java

// Get MapView from GemSurfaceView
GemSurfaceView gemSurfaceView = findViewById(R.id.gem_surface);
MapView mapView = gemSurfaceView.getMapView();

if (mapView != null) {
    mapView.setOnTouch(pos -> {
        // Set the cursor position
        mapView.setCursorScreenPosition(pos);

        // Get the landmarks at the cursor position
        LandmarkList landmarks = mapView.getCursorSelectionLandmarks();

        if (landmarks != null) {
            for (Landmark landmark : landmarks) {
                // handle landmark
                Log.d("Selection", "Selected landmark: " + landmark.getName());
            }
        }
    });
}

info

At higher zoom levels, landmarks provided by the cursorSelectionLandmarks property may lack some details for optimization purposes. Use SearchService to retrieve full landmark details if needed.

To unregister the callback:

Kotlin

mapView?.onTouch = null

Java

if (mapView != null) {
    mapView.setOnTouch(null);
}

info

The selected landmarks are returned by the cursorSelectionLandmarks property, which is accessed after updating the cursor's position. This step is essential because the SDK only detects landmarks that are positioned directly under the cursor.

danger

The cursor screen position is also used for determining the default screen position for centering (unless other values are specified). Modifying the screen position might change the behavior of centering in unexpected ways.

Street selection

The following code can be used to return selected streets under the cursor:

Kotlin

// Get MapView from GemSurfaceView
val gemSurfaceView = findViewById<GemSurfaceView>(R.id.gem_surface)
val mapView = gemSurfaceView.mapView

// Register touch callback to set cursor to tapped position
mapView?.onTouch = { point ->
    mapView.cursorScreenPosition = point
    val streets = mapView.cursorSelectionStreets

    val currentStreetName = if (streets?.isEmpty() != false) "Unnamed street" else streets.first().name
    Log.d("Selection", "Street name: $currentStreetName")
}

Java

// Get MapView from GemSurfaceView
GemSurfaceView gemSurfaceView = findViewById(R.id.gem_surface);
MapView mapView = gemSurfaceView.getMapView();

// Register touch callback to set cursor to tapped position
if (mapView != null) {
    mapView.setOnTouch(point -> {
        mapView.setCursorScreenPosition(point);
        LandmarkList streets = mapView.getCursorSelectionStreets();

        String currentStreetName = (streets == null || streets.isEmpty()) ? "Unnamed street" : streets.get(0).getName();
        Log.d("Selection", "Street name: " + currentStreetName);
    });
}

Street name can then be displayed on screen. This is the result:

Displaying a cursor selected street name

info

The visibility of the cursor has no impact whatsoever on the selection logic.

Getting the current cursor screen position is done by accessing the cursorScreenPosition property of MapView.

List of selection types

To summarize, there are multiple properties used to select different types of elements on the map. You can see all those in the following table.

Entity	Select method	Result type	Observations
Landmark	cursorSelectionLandmarks	LandmarkList?
Marker	cursorSelectionMarkers	MarkerMatchList?	Returns MarkerMatchList, not a MarkerList
OverlayItem	cursorSelectionOverlayItems	OverlayItemList?
Street	cursorSelectionStreets	LandmarkList?	Streets are handled as landmarks
Route	cursorSelectionRoutes	RouteList?
Path	cursorSelectionPath	Path?	Null is returned if no path is found
MapSceneObject	cursorSelectionSceneObject	MapSceneObject?	Null is returned if no map scene object is found
TrafficEvent	cursorSelectionTrafficEvents	TrafficEventList?

As you can see, when selecting markers a MarkerMatchList is returned. The match specifies information about the matched marker (the marker collection in which the marker resides, the index of the marker in the collection, the matched part index, the matched index of the point in the part).

You can also register callbacks that are called when the cursor is placed over elements on the MapView class:

• onCursorSelectionUpdatedLandmarks for landmarks
• onCursorSelectionUpdatedMarkerMatch for markers
• onCursorSelectionUpdatedOverlayItems for overlay items
• onCursorSelectionUpdatedRoutes for routes
• onCursorSelectionUpdatedTrafficEvents for traffic events

These callbacks are triggered whenever the selection changes - for example, when new elements are selected, the selection switches to different elements, or the selection is cleared (in which case the callback is invoked with null or an empty list).

To unregister a callback, simply set the corresponding property to null.

Capture the map view as an image

In certain situations, it may be necessary to save the map as an image - for example, to generate previews that are too expensive to redraw in real time. The Maps SDK for Android provides a dedicated method for capturing the map view through the GemSurfaceView.

Kotlin

// Using GemSurfaceView's takeScreenshot method
val surface = findViewById<GemSurfaceView>(R.id.gem_surface)
surface.takeScreenshot { bitmap ->
    // Convert to byte array if needed
    val stream = ByteArrayOutputStream()
    bitmap.compress(Bitmap.CompressFormat.JPEG, 90, stream)
    val imageBytes = stream.toByteArray()
}

Java

// Using GemSurfaceView's takeScreenshot method
GemSurfaceView surface = findViewById(R.id.gem_surface);
surface.takeScreenshot(bitmap -> {
    // Convert to byte array if needed
    ByteArrayOutputStream stream = new ByteArrayOutputStream();
    bitmap.compress(Bitmap.CompressFormat.JPEG, 90, stream);
    byte[] imageBytes = stream.toByteArray();
});

Tip

To ensure that any ongoing map animations or loading have completed, wait for the onViewRendered callback to be triggered with data transition status set to EViewDataTransitionStatus.Complete before capturing the image. Make sure to implement a timeout, as the onViewRendered is only triggered when the map is rendering - and will not be called if everything is already loaded.