SDK for Android Developer's Guide

Map Gestures

The MapGesture interface encapsulates all user interactions and touch gestures supported by SDK for Android. The MapGesture associated with a particular fragment can be retrieved from AndroidXMapFragment.getMapGesture(). The default behavior of the map for each gesture type may be used as-is, supplemented, or replaced entirely. The following table is a summary of the available gestures and their default behavior.

	To zoom the map in a fixed amount, tap the screen twice with one finger.
	To zoom out a fixed amount, tap the screen with two fingers.
	To move the map, press and hold one finger to the screen and move it in any direction.
	To tilt the map, press and hold two fingers to the screen and move them in a vertical direction. No behavior is predefined for other directions.
	To pan the map with momentum, press and swipe one finger on the screen. The map continues to move in the same direction and gradually slows to a stop.
	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, press and hold two fingers to the screen and rotate them together in a circle.
	Tap the screen with one finger. This gesture does not have a predefined map action.
	Press and hold one finger to the screen. This gesture does not have a predefined map action.

Map Gestures Example on GitHub

You can find an example that demonstrates this feature at https://github.com/heremaps/.

The OnGestureListener Interface

The OnGestureListener interface represents a listener to provide notification upon completion of a Map gesture event such as a single tap on a map.

For example, you can create a new OnGestureListener() as illustrated below.


// Map gesture listener
private class MyOnGestureListener implements OnGestureListener {

  @Override
  public void onPanStart() {
  }

  @Override
  public void onPanEnd() {
  }

  @Override
  public void onMultiFingerManipulationStart() {
  }

  @Override
  public void onMultiFingerManipulationEnd() {
  }

  @Override
  public boolean onMapObjectsSelected(List<ViewObject> objects) {
    return false;
  }

  @Override
  public boolean onTapEvent(PointF p) {
    return false;
  }

  @Override
  public boolean onDoubleTapEvent(PointF p) {
    return false;
  }

  @Override
  public void onPinchLocked() {
  }

  @Override
  public boolean onPinchZoomEvent(float scaleFactor, PointF p) {
    return false;
  }

  @Override
  public void onRotateLocked() {
  }

  @Override
  public boolean onRotateEvent(float rotateAngle) {
    return false;
  }

  @Override
  public boolean onTiltEvent(float angle) {
    return false;
  }

  @Override
  public boolean onLongPressEvent(PointF p) {
    return false;
  }

  @Override
  public void onLongPressRelease() {
  }

  @Override
  public boolean onTwoFingerTapEvent(PointF p) {
    return false;
  }
}

Note: The OnGestureListener methods that mention "rotate" and "tilt", such as onRotateEvent(float), are not supported. They are only defined here to maintain compatibility with the Premium Edition of HERE SDK.

To add the listener to your map, include a call to addOnGestureListener(OnGestureListener) after the map fragment has been successfully initialized as follows:

...
mapFragment.init(new OnEngineInitListener() {
  @Override
  public void onEngineInitializationCompleted(OnEngineInitListener.Error error) {
    if (error == OnEngineInitListener.Error.NONE) {
      // map fragment has been successfully initialized
      mapFragment.getMapGesture().addOnGestureListener(new MyOnGestureListener());
    }
  }
});
...

Note: After you add an OnGestureListener to an application, remember to call removeOnGestureListener(OnGestureListener) when you no longer need to listen for map events to free up application resources.

The default implementation of a OnGestureListener does not affect any of the standard HERE SDK touch gestures. Each method within the MyOnGestureListener class returns a value of false which stipulates that the application should not override the underlying action a device performs upon detecting a particular gesture.

If you want to customize an action your application performs upon detection of a particular gesture, you must include appropriate commands within a relevant method of the MyOnGestureListener class and return a value of true to override the default action as illustrated below with revisions to onTwoFingerTapEvent(PointF) method.


@Override
public boolean onTwoFingerTapEvent(PointF p) {
  // Reset the map view
  double level = map.getMinZoomLevel() + map.getMaxZoomLevel() / 2;
  map.setCenter(new GeoCoordinate(49.196261, -123.004773),
    Map.Animation.NONE);
  map.setZoomLevel(level);
  return true;
}

Note: Since the onTapEvent(PointF) event is always triggered before the onMapObjectsSelected(List<ViewObject>) event, you can leverage this behavior to implement your own object selection logic. While implementing object selection it is recommended that you use both Map.getSelectedObject(PointF) and Map.getSelectedObject(ViewRect) and combine the results so that the user's tap input is interpreted over a larger area rather than only a single point.

After the revision the basic application responds to each two-finger tap gesture by returning to its initial view (the view displayed upon application launch). Other touch gestures continue to trigger standard HERE SDK actions.