Package com.esri.arcgisruntime.mapping.view

Class DefaultMapViewOnTouchListener

  • All Implemented Interfaces:
    android.view.GestureDetector.OnDoubleTapListener, android.view.GestureDetector.OnGestureListener, android.view.ScaleGestureDetector.OnScaleGestureListener, android.view.View.OnTouchListener, MapView.OnTouchListener
    public class DefaultMapViewOnTouchListener
extends java.lang.Object
implements MapView.OnTouchListener
    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.

    Since:
    100.0.0

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static int DOUBLE_TAP_TIMEOUT
      Default double-tap timeout in milliseconds as defined by android.view.ViewConfiguration.getDoubleTapTimeout(), which can be used to detect when to trigger/cancel a double-tap.
      protected static int FLING_VELOCITY_THRESHOLD_DP
      Density-independent velocity threshold (dp per seconds) for calculating a device dependent (pixel based) fling gesture threshold.
      protected static int LONG_PRESS_TIMEOUT
      Default long press timeout in milliseconds as defined by android.view.ViewConfiguration.getLongPressTimeout(), which can be used to detect when to trigger/cancel a long press.
      protected MapView mMapView  
      protected static 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.

    • Constructor Summary

      Constructors 
      Constructor Description
      DefaultMapViewOnTouchListener​(android.content.Context context, MapView mapView)
      Constructs a DefaultMapViewOnTouchListener with the given Context and MapView.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      PinchToZoomGestureDetector getPinchToZoomGestureDetector()
      Gets the PinchToZoomGestureDetector.
      boolean onDoubleTap​(android.view.MotionEvent e)
      Notified when a double-tap with a single pointer is performed within the double-tap timeout as defined at android.view.ViewConfiguration.getDoubleTapTimeout().
      boolean onDoubleTapEvent​(android.view.MotionEvent e)
      This method is not called in the default implementation.
      boolean onDoubleTouchDrag​(android.view.MotionEvent event)
      Notified when a double-touch-and-drag gesture is performed on the MapView.
      boolean onDown​(android.view.MotionEvent e)
      Notified when a pointer is placed on the screen.
      boolean onFling​(android.view.MotionEvent e1, android.view.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​(android.view.MotionEvent e)
      Notified when a single pointer is pressed and held for a certain length of time on the screen.
      boolean onMultiPointerTap​(android.view.MotionEvent event)
      Notified when a multi-pointer-tap gesture is performed on the MapView.
      boolean onRotate​(android.view.MotionEvent event, double rotationAngle)
      Notified when a rotate gesture is performed on the MapView.
      boolean onScale​(android.view.ScaleGestureDetector detector)
      Notified when two pointers are pinched closer together or farther apart.
      boolean onScaleBegin​(android.view.ScaleGestureDetector detector)
      Notified when a pinch gesture begins.
      void onScaleEnd​(android.view.ScaleGestureDetector detector)
      Notified when a pinch gesture ends.
      boolean onScroll​(android.view.MotionEvent e1, android.view.MotionEvent e2, float distanceX, float distanceY)
      Notified when the screen is scrolled (with one or two pointers).
      void onShowPress​(android.view.MotionEvent e)
      This method does not perform any actions, and is not called in this default implementation.
      boolean onSingleTapConfirmed​(android.view.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​(android.view.MotionEvent e)
      Notified when a single-tap pointer goes up, but before the single-tap event is confirmed.
      boolean onTouch​(android.view.View view, android.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​(android.view.MotionEvent e)
      Notified when a pointer is lifted up, following any combination of gesture actions.
      void setPinchToZoomGestureDetector​(PinchToZoomGestureDetector pinchToZoomGestureDetector)
      Sets a PinchToZoomGestureDetector that is used instead of the ScaleGestureDetector to perform pinch-to-zoom gestures.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • DOUBLE_TAP_TIMEOUT

        protected static final int DOUBLE_TAP_TIMEOUT
        Default double-tap timeout in milliseconds as defined by android.view.ViewConfiguration.getDoubleTapTimeout(), which can be used to detect when to trigger/cancel a double-tap.
        Since:
        100.0.0

      • LONG_PRESS_TIMEOUT

        protected static final int LONG_PRESS_TIMEOUT
        Default long press timeout in milliseconds as defined by android.view.ViewConfiguration.getLongPressTimeout(), which can be used to detect when to trigger/cancel a long press.
        Since:
        100.0.0

      • TAP_TIMEOUT

        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.
        Since:
        100.0.0

      • FLING_VELOCITY_THRESHOLD_DP

        protected static final int FLING_VELOCITY_THRESHOLD_DP
        Density-independent velocity threshold (dp per seconds) for calculating a device dependent (pixel based) fling gesture threshold. For example, on a XHDPI (320DPI) device with display density 2, it will produce a 850x2 pixel per seconds fling threshold for combined x and y velocity.
        Since:
        100.7.0
        See Also:
        Constant Field Values

      • mMapView

        protected final MapView mMapView

    • Constructor Detail

      • DefaultMapViewOnTouchListener

        public DefaultMapViewOnTouchListener​(android.content.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
        Since:
        100.0.0

    • Method Detail

      • onTouch

        public boolean onTouch​(android.view.View view,
                       android.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.
        Specified by:
        onTouch in interface android.view.View.OnTouchListener
        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
        Since:
        100.0.0

      • onDown

        public boolean onDown​(android.view.MotionEvent e)
        Notified when a pointer is placed on the screen. This implementation does not perform any actions, and always returns false.
        Specified by:
        onDown in interface android.view.GestureDetector.OnGestureListener
        Parameters:
        e - the motion event
        Returns:
        always false
        Since:
        100.0.0

      • onUp

        public boolean onUp​(android.view.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.
        Specified by:
        onUp in interface MapView.OnTouchListener
        Parameters:
        e - the motion event that completed the up gesture, triggering this onUp call
        Returns:
        always false
        Since:
        100.0.0

      • onShowPress

        public void onShowPress​(android.view.MotionEvent e)
        This method does not perform any actions, and is not called in this default implementation.
        Specified by:
        onShowPress in interface android.view.GestureDetector.OnGestureListener
        Parameters:
        e - the motion event
        Since:
        100.0.0

      • onSingleTapUp

        public boolean onSingleTapUp​(android.view.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.
        Specified by:
        onSingleTapUp in interface android.view.GestureDetector.OnGestureListener
        Parameters:
        e - the up motion event that completed the single-tap gesture
        Returns:
        always false
        Since:
        100.0.0

      • onScroll

        public boolean onScroll​(android.view.MotionEvent e1,
                        android.view.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.
        Specified by:
        onScroll in interface android.view.GestureDetector.OnGestureListener
        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
        Since:
        100.0.0

      • onLongPress

        public void onLongPress​(android.view.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 android.view.ViewConfiguration.getLongPressTimeout().

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

        Specified by:
        onLongPress in interface android.view.GestureDetector.OnGestureListener
        Parameters:
        e - the long-press motion event
        Since:
        100.0.0

      • onFling

        public boolean onFling​(android.view.MotionEvent e1,
                       android.view.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.
        Specified by:
        onFling in interface android.view.GestureDetector.OnGestureListener
        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

      • onScale

        public boolean onScale​(android.view.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.
        Specified by:
        onScale in interface android.view.ScaleGestureDetector.OnScaleGestureListener
        Parameters:
        detector - the scale gesture detector used to detect the events
        Returns:
        true if the listener has consumed the event; false otherwise
        Since:
        100.0.0

      • onScaleBegin

        public boolean onScaleBegin​(android.view.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(android.view.ScaleGestureDetector) and onScaleEnd(android.view.ScaleGestureDetector) will never be called.
        Specified by:
        onScaleBegin in interface android.view.ScaleGestureDetector.OnScaleGestureListener
        Parameters:
        detector - the scale gesture detector used to detect the events
        Returns:
        always true
        Since:
        100.0.0

      • onScaleEnd

        public void onScaleEnd​(android.view.ScaleGestureDetector detector)
        Notified when a pinch gesture ends. This implementation does not perform any actions.
        Specified by:
        onScaleEnd in interface android.view.ScaleGestureDetector.OnScaleGestureListener
        Parameters:
        detector - the scale gesture detector used to detect the events
        Since:
        100.0.0

      • onRotate

        public boolean onRotate​(android.view.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.
        Specified by:
        onRotate in interface MapView.OnTouchListener
        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
        Since:
        100.0.0

      • onMultiPointerTap

        public boolean onMultiPointerTap​(android.view.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.
        Specified by:
        onMultiPointerTap in interface MapView.OnTouchListener
        Parameters:
        event - the motion event that completed the multi-pointer tap gesture
        Returns:
        true if the listener has consumed the event; false otherwise
        Since:
        100.0.0

      • onSingleTapConfirmed

        public boolean onSingleTapConfirmed​(android.view.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.
        Specified by:
        onSingleTapConfirmed in interface android.view.GestureDetector.OnDoubleTapListener
        Parameters:
        e - the last motion event of the single-tap. The action of the event will always be MotionEvent.ACTION_UP.
        Returns:
        always true
        Since:
        100.0.0

      • onDoubleTap

        public boolean onDoubleTap​(android.view.MotionEvent e)
        Notified when a double-tap with a single pointer is performed within the double-tap timeout as defined at android.view.ViewConfiguration.getDoubleTapTimeout(). This implementation zooms the map in by a factor of two, with animation.
        Specified by:
        onDoubleTap in interface android.view.GestureDetector.OnDoubleTapListener
        Parameters:
        e - the motion event
        Returns:
        true if the listener has consumed the event; false otherwise
        Since:
        100.0.0

      • onDoubleTapEvent

        public boolean onDoubleTapEvent​(android.view.MotionEvent e)
        This method is not called in the default implementation. This implementation does not perform any actions, and always returns false.
        Specified by:
        onDoubleTapEvent in interface android.view.GestureDetector.OnDoubleTapListener
        Parameters:
        e - the motion event
        Returns:
        always false
        Since:
        100.0.0

      • onDoubleTouchDrag

        public boolean onDoubleTouchDrag​(android.view.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 zooms the map (non-animated) in if the pointer is dragged downwards, or zooms out if the pointer is dragged upwards, with the zoom being anchored at the center of the MapView.
        Specified by:
        onDoubleTouchDrag in interface MapView.OnTouchListener
        Parameters:
        event - the motion event that triggered the current onDoubleTouchDrag gesture
        Returns:
        true if the listener has consumed the event; false otherwise
        Since:
        100.0.0

      • setPinchToZoomGestureDetector

        public void setPinchToZoomGestureDetector​(PinchToZoomGestureDetector pinchToZoomGestureDetector)
        Sets a PinchToZoomGestureDetector that is used instead of the ScaleGestureDetector to perform pinch-to-zoom gestures. As of Android 7 (Nougat) the android.view.ScaleGestureDetector doesn't behave as desired, which is detrimental to the user experience of pinch-zooming a MapView. The PinchToZoomGestureDetector aims to improve the user experience of pinch-zooming. Note that after setting a PinchToZoomGestureDetector, the following methods are not being called:
        Parameters:
        pinchToZoomGestureDetector - a PinchToZoomGestureDetector, or null to use the android.view.ScaleGestureDetector for pinch-zooming
        Since:
        100.9.0