public class

DefaultMapViewOnTouchListener

extends Object
implements MapView.OnTouchListener
java.lang.Object
   ↳ com.esri.arcgisruntime.mapping.view.DefaultMapViewOnTouchListener

Class Overview

Provides the default gestures handling behaviour for the MapView, implementing MapView.OnTouchListener. This provides additional gesture control over the standard Android GestureDetector.

An instance of DefaultMapViewOnTouchListener is set on the MapView by default, providing the following behaviour:

  • double-tap - Zooms in by a factor of 2.
  • multi-pointer-tap - Zooms out by a factor of 2.
  • pinch - Zooms in and out interactively. Pinch-open zooms in, and pinch-close zooms out.
  • drag or fling - Pans the map interactively and may result in a fling depending on the speed of the pan gesture when the pointer is lifted.
  • double-touch followed by vertical drag - Triggers continual zooming in or out. On second touch, keep pointer on screen and drag upwards to zoom out, downwards to zoom in. Horizontal movement is ignored.
  • rotate - Rotates the map interactively. Pinch-open and pinch-closed gestures to zoom can be used in combination with rotate.

More information about these gestures can be found on the corresponding methods of this class.

You can override the default gestures of a MapView by creating a new touch listener class that implements MapView.OnTouchListener. You may wish to inherit from DefaultMapViewOnTouchListener instead of directly implementing OnTouchListener. Advantages of this approach are you only need to override the methods you want to control, and can also call the super class's implementation before or after your custom logic. For example, to disable the ability for the user to interactively pan the MapView, override the onFling and onScroll events and return true without performing any map navigation.

Summary

Fields
protected static final int DOUBLE_TAP_TIMEOUT Default double-tap timeout in milliseconds as defined by getDoubleTapTimeout(), which can be used to detect when to trigger/cancel a double-tap.
protected static final int LONG_PRESS_TIMEOUT Default long press timeout in milliseconds as defined by getLongPressTimeout(), which can be used to detect when to trigger/cancel a long press.
protected static final int TAP_TIMEOUT Default tap timeout in milliseconds is set to the LONG_PRESS_TIMEOUT minus 1 so that any single pointer event that doesn't involve an ACTION_MOVE will be considered either a single-tap or a long press.
protected final MapView mMapView
Public Constructors
DefaultMapViewOnTouchListener(Context context, MapView mapView)
Constructs a DefaultMapViewOnTouchListener with the given Context and MapView.
Public Methods
boolean onDoubleTap(MotionEvent e)
Notified when a double-tap with a single pointer is performed within the double-tap timeout as defined at getDoubleTapTimeout().
boolean onDoubleTapEvent(MotionEvent e)
This method is not called in the default implementation.
boolean onDoubleTouchDrag(MotionEvent event)
Notified when a double-touch-and-drag gesture is performed on the MapView.
boolean onDown(MotionEvent e)
Notified when a pointer is placed on the screen.
boolean onFling(MotionEvent e1, MotionEvent e2, float velocityX, float velocityY)
Notified when a single pointer is lifted from the screen after being dragged and released, if the pointer movement is above a certain velocity threshold.
void onLongPress(MotionEvent e)
Notified when a single pointer is pressed and held for a certain length of time on the screen.
boolean onMultiPointerTap(MotionEvent event)
Notified when a multi-pointer-tap gesture is performed on the MapView.
boolean onRotate(MotionEvent event, double rotationAngle)
Notified when a rotate gesture is performed on the MapView.
boolean onScale(ScaleGestureDetector detector)
Notified when two pointers are pinched closer together or farther apart.
boolean onScaleBegin(ScaleGestureDetector detector)
Notified when a pinch gesture begins.
void onScaleEnd(ScaleGestureDetector detector)
Notified when a pinch gesture ends.
boolean onScroll(MotionEvent e1, MotionEvent e2, float distanceX, float distanceY)
Notified when the screen is scrolled (with one or two pointers).
void onShowPress(MotionEvent e)
This method does not perform any actions, and is not called in this default implementation.
boolean onSingleTapConfirmed(MotionEvent e)
Notified when a single-tap has been confirmed on the MapView, meaning that a double-tap has not been detected within the double-tap timeout.
boolean onSingleTapUp(MotionEvent e)
Notified when a single-tap pointer goes up, but before the single-tap event is confirmed.
boolean onTouch(View view, MotionEvent event)
Called when a touch event is dispatched to a view, this method determines which gesture is being performed and delegates to the corresponding method.
boolean onUp(MotionEvent e)
Notified when a pointer is lifted up, following any combination of gesture actions.
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.view.GestureDetector.OnDoubleTapListener
From interface android.view.GestureDetector.OnGestureListener
From interface android.view.ScaleGestureDetector.OnScaleGestureListener
From interface android.view.View.OnTouchListener
From interface com.esri.arcgisruntime.mapping.view.MapView.OnTouchListener

Fields

protected static final int DOUBLE_TAP_TIMEOUT

Default double-tap timeout in milliseconds as defined by getDoubleTapTimeout(), which can be used to detect when to trigger/cancel a double-tap.

protected static final int LONG_PRESS_TIMEOUT

Default long press timeout in milliseconds as defined by getLongPressTimeout(), which can be used to detect when to trigger/cancel a long press.

protected static final int TAP_TIMEOUT

Default tap timeout in milliseconds is set to the LONG_PRESS_TIMEOUT minus 1 so that any single pointer event that doesn't involve an ACTION_MOVE will be considered either a single-tap or a long press.

protected final MapView mMapView

Public Constructors

public DefaultMapViewOnTouchListener (Context context, MapView mapView)

Constructs a DefaultMapViewOnTouchListener with the given Context and MapView.

Parameters
context the context from which this is being created
mapView the MapView with which to interact

Public Methods

public boolean onDoubleTap (MotionEvent e)

Notified when a double-tap with a single pointer is performed within the double-tap timeout as defined at getDoubleTapTimeout(). This implementation zooms the map in by a factor of two, with animation.

Parameters
e the motion event
Returns
  • true if the listener has consumed the event; false otherwise

public boolean onDoubleTapEvent (MotionEvent e)

This method is not called in the default implementation. This implementation does not perform any actions, and always returns false.

Parameters
e the motion event
Returns
  • always false

public boolean onDoubleTouchDrag (MotionEvent event)

Notified when a double-touch-and-drag gesture is performed on the MapView. The gesture consists of a single-pointer tap-and-touch where instead of lifting the pointer after the second tap, it is held on the screen and then dragged. This implementation continuously zooms the map in if the pointer is dragged downwards, or zooms out if the pointer is dragged upwards.

Parameters
event the motion event that triggered the current onDoubleTouchDrag gesture
Returns
  • true if the listener has consumed the event; false otherwise

public boolean onDown (MotionEvent e)

Notified when a pointer is placed on the screen. This implementation does not perform any actions, and always returns false.

Parameters
e the motion event
Returns
  • always false

public boolean onFling (MotionEvent e1, MotionEvent e2, float velocityX, float velocityY)

Notified when a single pointer is lifted from the screen after being dragged and released, if the pointer movement is above a certain velocity threshold. This implementation will pan the map in the direction of the gesture, with animation.

Parameters
e1 the event representing the from position
e2 the event representing the to position
velocityX the velocity in the x direction
velocityY the velocity in the y direction
Returns
  • true if the listener has consumed the event; false otherwise

public void onLongPress (MotionEvent e)

Notified when a single pointer is pressed and held for a certain length of time on the screen. The minimum time that causes this method to be called is defined by getLongPressTimeout().

This implementation shows a map magnifier, if isMagnifierEnabled() is true, helping the user to more precisely locate the pointer on the map. When the pointer is next released, the magifier will be hidden, and onUp(MotionEvent) will be notified.

Parameters
e the long-press motion event

public boolean onMultiPointerTap (MotionEvent event)

Notified when a multi-pointer-tap gesture is performed on the MapView. The gesture consists of a single-tap with multiple pointers on the screen. This implementation zooms the map out by a factor of two, with animation.

Parameters
event the motion event that completed the multi-pointer tap gesture
Returns
  • true if the listener has consumed the event; false otherwise

public boolean onRotate (MotionEvent event, double rotationAngle)

Notified when a rotate gesture is performed on the MapView. The gesture consists of two pointers rotating clockwise or counter clockwise around a midpoint. This implementation rotates the map based on the rotation angle of the gesture. Map rotation only begins once the rotation angle is greater than a small tolerance, in order to avoid unintentional rotation. Additionally, the map is not rotated if the rotate gesture occurs after a pinch (onScale(ScaleGestureDetector)) gesture has begun, again to avoid unintentional rotation.

Parameters
event the motion event that triggered the current onRotate call
rotationAngle the angle of rotation of the current rotation gesture, in degrees counterclockwise. Negative numbers indicate clockwise rotation.
Returns
  • true if the listener has consumed the event; false otherwise

public boolean onScale (ScaleGestureDetector detector)

Notified when two pointers are pinched closer together or farther apart. This implementation zooms the map out if pointers are moved together, and zooms in if moved apart.

Parameters
detector the scale gesture detector used to detect the events
Returns
  • true if the listener has consumed the event; false otherwise

public boolean onScaleBegin (ScaleGestureDetector detector)

Notified when a pinch gesture begins. This implementation does not perform any actions, and always returns true. Note - if you override this method and return false then onScale(ScaleGestureDetector) and onScaleEnd(ScaleGestureDetector) will never be called.

Parameters
detector the scale gesture detector used to detect the events
Returns
  • always true

public void onScaleEnd (ScaleGestureDetector detector)

Notified when a pinch gesture ends. This implementation does not perform any actions.

Parameters
detector the scale gesture detector used to detect the events

public boolean onScroll (MotionEvent e1, MotionEvent e2, float distanceX, float distanceY)

Notified when the screen is scrolled (with one or two pointers). This implementation pans the map by a distance and direction corresponding to the pointer movement. In the case of two pointers, the midpoint of the pointers is used for panning.

Parameters
e1 the motion event representing the pointer from position
e2 the motion event representing the pointer to position
distanceX the distance travelled in the x direction
distanceY the distance travelled in the y direction
Returns
  • true if the listener has consumed the event; false otherwise

public void onShowPress (MotionEvent e)

This method does not perform any actions, and is not called in this default implementation.

Parameters
e the motion event

public boolean onSingleTapConfirmed (MotionEvent e)

Notified when a single-tap has been confirmed on the MapView, meaning that a double-tap has not been detected within the double-tap timeout. This implementation does not perform any actions, and always returns true.

Parameters
e the last motion event of the single-tap. The action of the event will always be MotionEvent.ACTION_UP.
Returns
  • always true

public boolean onSingleTapUp (MotionEvent e)

Notified when a single-tap pointer goes up, but before the single-tap event is confirmed. This implementation does not perform any actions, and always returns false.

Parameters
e the up motion event that completed the single-tap gesture
Returns
  • always false

public boolean onTouch (View view, MotionEvent event)

Called when a touch event is dispatched to a view, this method determines which gesture is being performed and delegates to the corresponding method.

Parameters
view the view the touch event has been dispatched to
event the MotionEvent object containing full information about the event
Returns
  • true if the listener has consumed the event; false otherwise

public boolean onUp (MotionEvent e)

Notified when a pointer is lifted up, following any combination of gesture actions. This implementation does not perform any actions, and always returns false.

Parameters
e the motion event that completed the up gesture, triggering this onUp call
Returns
  • always false