Class DefaultSceneViewOnTouchListener

  • All Implemented Interfaces:
    android.view.ScaleGestureDetector.OnScaleGestureListener, android.view.View.OnTouchListener

    public class DefaultSceneViewOnTouchListener
    extends Object
    implements android.view.View.OnTouchListener, android.view.ScaleGestureDetector.OnScaleGestureListener
    Provides the default gesture handling behaviour for the SceneView.

    An instance of DefaultSceneViewOnTouchListener is set on the SceneView by default, providing the following behaviour:

    • double-tap - Zooms in by a factor.
    • multi-pointer-tap - Zooms out by a factor.
    • pinch - Zooms in and out interactively. Pinch-open zooms in, and pinch-close zooms out.
    • drag or fling - Pans the scene 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.
    • two-pointer-rotate - Rotates the scene interactively. Pinch-open and pinch-close gestures to zoom can be used in combination with rotate.
    • two-pointer vertical drag - Changes the pitch of the scene interactively, tilting the camera around the midpoint of the two pointers. Cannot be used in combination with rotating or zooming.

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

    You can override the default gestures of a SceneView by creating a new touch listener class that implements View.OnTouchListener. You may wish to inherit from DefaultSceneViewOnTouchListener 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 scene, override the onFling and onScroll events and return true without performing any scene navigation.

    Since:
    100.1.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 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 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.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean onDoubleTap​(android.view.MotionEvent motionEvent)
      Notified when a double-tap with a single pointer is performed within the double-tap timeout as defined at android.view.ViewConfiguration.getDoubleTapTimeout().
      boolean onDoubleTouchDrag​(android.view.MotionEvent motionEvent)
      Notified when a double-touch-and-drag gesture is performed on the SceneView.
      boolean onFling()
      Notified when a single pointer is lifted from the screen after being dragged.
      void onLongPress​(android.view.MotionEvent motionEvent)
      Notified when a single pointer is pressed and held for a certain length of time on the screen.
      boolean onMultiPointerTap​(android.view.MotionEvent motionEvent)
      Notified when a multi-pointer-tap gesture is performed on the SceneView.
      boolean onScale​(android.view.ScaleGestureDetector scaleGestureDetector)
      Notified when two pointers are pinched closer together or farther apart.
      boolean onScaleBegin​(android.view.ScaleGestureDetector scaleGestureDetector)
      Notified when a pinch gesture begins.
      void onScaleEnd​(android.view.ScaleGestureDetector scaleGestureDetector)
      Notified when a pinch gesture ends.
      boolean onScroll​(android.view.MotionEvent motionEventFrom, android.view.MotionEvent motionEventTo, float distanceX, float distanceY)
      Notified when the screen is scrolled.
      boolean onSinglePointerDown​(android.view.MotionEvent motionEvent)
      Notified when a single pointer is placed on the screen.
      boolean onSinglePointerUp​(android.view.MotionEvent motionEvent)
      Notified when a single pointer is lifted up, following any combination of gesture actions.
      boolean onSingleTapConfirmed​(android.view.MotionEvent motionEvent)
      Notified when a single-tap has been confirmed on the SceneView, meaning that a double-tap has not been detected within the double-tap timeout.
      boolean onSingleTapUp​(android.view.MotionEvent motionEvent)
      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 motionEvent)
      Called when a touch event is dispatched to the SceneView, this method determines which gesture is being performed and delegates to the corresponding method.
      boolean onTwoPointerPitch​(android.view.MotionEvent motionEvent, double pitchDelta)
      Notified when a pitch gesture is performed on the SceneView.
      boolean onTwoPointerRotate​(android.view.MotionEvent motionEvent, double rotationDelta)
      Notified when a rotate gesture is performed on the SceneView.
    • 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.1.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.1.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.1.0
    • Constructor Detail

      • DefaultSceneViewOnTouchListener

        public DefaultSceneViewOnTouchListener​(SceneView sceneView)
        Creates a new instance of DefaultSceneViewOnTouchListener with the given SceneView.
        Parameters:
        sceneView - the SceneView with which to interact
        Throws:
        IllegalArgumentException - if sceneView is null
        Since:
        100.1.0
    • Method Detail

      • onTouch

        public boolean onTouch​(android.view.View view,
                               android.view.MotionEvent motionEvent)
        Called when a touch event is dispatched to the SceneView, 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
        motionEvent - the MotionEvent object containing full information about the event
        Returns:
        true if the listener has consumed the event; false otherwise
        Since:
        100.1.0
      • onMultiPointerTap

        public boolean onMultiPointerTap​(android.view.MotionEvent motionEvent)
        Notified when a multi-pointer-tap gesture is performed on the SceneView. The gesture consists of a single-tap with multiple pointers on the screen. This implementation zooms the scene out by a certain factor with animation.
        Parameters:
        motionEvent - the motion event that completed the multi-pointer tap gesture
        Returns:
        true if the listener has consumed the event; false otherwise
        Since:
        100.1.0
      • onDoubleTouchDrag

        public boolean onDoubleTouchDrag​(android.view.MotionEvent motionEvent)
        Notified when a double-touch-and-drag gesture is performed on the SceneView. The gesture consists of a single-pointer tap-and-touch where instead of lifting the pointer after the second touch, it is held on the screen and then dragged. This implementation continuously zooms the scene in if the pointer is dragged downwards, or zooms out if the pointer is dragged upwards.
        Parameters:
        motionEvent - the motion event that triggered the current onDoubleTouchDrag gesture
        Returns:
        true if the listener has consumed the event; false otherwise
        Since:
        100.1.0
      • onSinglePointerDown

        public boolean onSinglePointerDown​(android.view.MotionEvent motionEvent)
        Notified when a single pointer is placed on the screen. This implementation does not perform any actions, and always returns false.
        Parameters:
        motionEvent - the motion event
        Returns:
        always false
        Since:
        100.1.0
      • onSinglePointerUp

        public boolean onSinglePointerUp​(android.view.MotionEvent motionEvent)
        Notified when a single pointer is lifted up, following any combination of gesture actions. This implementation does not perform any actions, and always returns false.
        Parameters:
        motionEvent - the motion event that completed the up gesture, triggering this onSinglePointerUp call
        Returns:
        always false
        Since:
        100.1.0
      • onTwoPointerPitch

        public boolean onTwoPointerPitch​(android.view.MotionEvent motionEvent,
                                         double pitchDelta)
        Notified when a pitch gesture is performed on the SceneView. The gesture consists of two pointers placed horizontally on the screen and moved up or down. This implementation rotates the camera by a certain pitch angle around an anchor point. The pitch delta is determined by how far the pointers are moved horizontally up or down.
        Parameters:
        motionEvent - the motion event that triggered this onTwoPointerPitch gesture
        pitchDelta - an angle in degrees by which the camera is rotated around an anchor point
        Returns:
        true if the listener has consumed the event; false otherwise
        Since:
        100.1.0
      • onTwoPointerRotate

        public boolean onTwoPointerRotate​(android.view.MotionEvent motionEvent,
                                          double rotationDelta)
        Notified when a rotate gesture is performed on the SceneView. The gesture consists of two pointers rotating clockwise or counter clockwise around a midpoint. This implementation rotates the scene based on the rotation angle of the gesture. Scene rotation only begins once the rotation angle is greater than a small tolerance, in order to avoid unintentional rotation. Additionally, the scene is not rotated if the rotate gesture occurs after a pinch (onScale(ScaleGestureDetector)) gesture has begun, again to avoid unintentional rotation.
        Parameters:
        motionEvent - the motion event that triggered the current onTwoPointerRotate call
        rotationDelta - the angle difference in degrees of the current rotation gesture. Negative numbers indicate counter-clockwise rotation, positive numbers clockwise rotation.
        Returns:
        true if the listener has consumed the event; false otherwise
        Since:
        100.1.0
      • onSingleTapConfirmed

        public boolean onSingleTapConfirmed​(android.view.MotionEvent motionEvent)
        Notified when a single-tap has been confirmed on the SceneView, meaning that a double-tap has not been detected within the double-tap timeout. This implementation does not perform any actions, and always returns false.
        Parameters:
        motionEvent - the last motion event of the single-tap. The action of the event will always be MotionEvent.ACTION_UP.
        Returns:
        always false
        Since:
        100.1.0
      • onDoubleTap

        public boolean onDoubleTap​(android.view.MotionEvent motionEvent)
        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 certain factor with animation.
        Parameters:
        motionEvent - the motion event
        Returns:
        true if the listener has consumed the event; false otherwise
        Since:
        100.1.0
      • onSingleTapUp

        public boolean onSingleTapUp​(android.view.MotionEvent motionEvent)
        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:
        motionEvent - the up motion event that completed the single-tap gesture
        Returns:
        always false
        Since:
        100.1.0
      • onScroll

        public boolean onScroll​(android.view.MotionEvent motionEventFrom,
                                android.view.MotionEvent motionEventTo,
                                float distanceX,
                                float distanceY)
        Notified when the screen is scrolled. This implementation pans the scene by a distance and direction corresponding to the pointer movement.
        Parameters:
        motionEventFrom - the motion event representing the pointer from position
        motionEventTo - 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.1.0
      • onLongPress

        public void onLongPress​(android.view.MotionEvent motionEvent)
        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().
        Parameters:
        motionEvent - the long-press motion event
        Since:
        100.1.0
      • onFling

        public boolean onFling()
        Notified when a single pointer is lifted from the screen after being dragged. This implementation will pan the scene in the direction of the gesture with animation.
        Returns:
        true if the listener has consumed the event; false otherwise
        Since:
        100.1.0
      • onScale

        public boolean onScale​(android.view.ScaleGestureDetector scaleGestureDetector)
        Notified when two pointers are pinched closer together or farther apart. This implementation zooms the scene out if pointers are moved together, and zooms in if moved apart.
        Specified by:
        onScale in interface android.view.ScaleGestureDetector.OnScaleGestureListener
        Parameters:
        scaleGestureDetector - the scale gesture detector used to detect the events
        Returns:
        true if the listener has consumed the event; false otherwise
        Since:
        100.1.0
      • onScaleBegin

        public boolean onScaleBegin​(android.view.ScaleGestureDetector scaleGestureDetector)
        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:
        scaleGestureDetector - the scale gesture detector used to detect the events
        Returns:
        always true
        Since:
        100.1.0
      • onScaleEnd

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