The meaning of returning false from OnGestureListener.onDown()

Question

According to android training if you extend GestureDetector.SimpleOnGestureListener, and return false from onDown(...) than the other methods of GestureDetector.SimpleOnGestureListener will never get called:

Whether or not you use GestureDetector.OnGestureListener, it's best practice to implement an onDown() method that returns true. This is because all gestures begin with an onDown() message. If you return false from onDown(), as GestureDetector.SimpleOnGestureListener does by default, the system assumes that you want to ignore the rest of the gesture, and the other methods of GestureDetector.OnGestureListener never get called. This has the potential to cause unexpected problems in your app. The only time you should return false from onDown() is if you truly want to ignore an entire gesture.

However, in my simple test onScroll(...) is been called.

public void onCreate(Bundle savedInstanceState) {
    mDetector = new GestureDetectorCompat(this, MyGestureListener);
}


public boolean onTouchEvent(MotionEvent event) { 
    mDetector.onTouchEvent(event);
    return true;
}


class MyGestureListener extends GestureDetector.SimpleOnGestureListener {
    private boolean scrollEvent;

    @Override
    public boolean onDown (MotionEvent event) {
        Log.v("GESTURE", "onDown ");
        return false;
    }

    @Override
    public boolean onScroll (MotionEvent e1, MotionEvent e2, float distanceX, float distanceY) {
        Log.v("GESTURE", "onScroll");
        return true;
    }

Another similar issue is the next definition, again from the same android training page:

a return value of true from the individual on methods indicates that you have handled the touch event. A return value of false passes events down through the view stack until the touch has been successfully handled.

How does this settle with the previous quotation?

Answer 1

The only time you should return false from onDown() is if you truly want to ignore an entire gesture.

That pretty much says it all.

The point is the onDown(...) method receives a MotionEvent as a parameter, You have the option to analyse the MotionEvent in the onDown(...) method and if it isn't something you want to handle then you return false.

A MotionEvent carries a lot of detailed information which includes position of the start of the gesture (for example) - if it's outside of an area you want to handle then return false otherwise return true.

If you return true from onDown(...) the other methods will then be called. Each of those methods again have the option to analyse and handle the various parameters passed to them. If you handle an event in any of those methods and don't want any further action then return true from those methods otherwise the other methods will be called (possibly in a super class depending on your code implementation).

Gestures are complex and involve down and up actions as well as movement in any direction. Allowing the option to reject a gesture (by returning false in onDown(...)) makes things more versatile.

EDIT: In some situations there may be a case where you have multiple views on a screen. The MotionEvent passed to onDown(...) will contain information about where the gesture starts. If you don't wan't some areas of your screen to react to gestures then you return false when you've checked the start position of the gesture.

Answer 2

Actually, I don't know it correct or not but this definition will correct in this case

Example, you handle onTouch for a TextView (TextView default is not clickable)

class MainActivity : AppCompatActivity() {
    private lateinit var detector: GestureDetectorCompat

    public override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        detector = GestureDetectorCompat(this, MyGestureListener())


        findViewById<View>(R.id.textview).setOnTouchListener { v, event ->
            // 
            // Don't always return true here (like OP post)
            // 
            detector.onTouchEvent(event) // Kotlin code, equivalent to "return detector.onTouchEvent(event)" in Java
        }
    }

    inner class MyGestureListener : GestureDetector.SimpleOnGestureListener() {

        override fun onDown(event: MotionEvent): Boolean {
            Log.d(DEBUG_TAG, "onDown: " + event.toString())
            return false
        }

        override fun onFling(event1: MotionEvent, event2: MotionEvent,
                         velocityX: Float, velocityY: Float): Boolean {
            Log.d(DEBUG_TAG, "onFling: " + event1.toString() + event2.toString())
            return true
        }

        override fun onSingleTapUp(event: MotionEvent?): Boolean {
            Log.d(DEBUG_TAG, "onSingleTapUp: " + event.toString())
            return true
        }
    }
}

In this case:
If your onDown function return FALSE, on onFling and onSingleTapUp NEVER called

If your onDown function return TRUE, on onFling and onSingleTapUp CAN called

Note

This definition will correct if the view is not clickable.
If the view is clickable, ALL event will CALLED either onDown return false or onDown return true

Hope it help and please correct me if I am wrong DEMO

Answer 3

I am not sure whether i am right or wrong, but following are the points in which user should return false from onDown()

1. When user don't want to react to gesture on screen.
2. When User want to implement or use onLongPress() method of touch event.

For point 1 both @Squonk and @Phan Van Linh have provided explantation, so i am explaining only 2nd point.

Point 2: When User want to implement onLongPress() method.

public MySurfaceView(Context context, IAttributeSet attrs):base(context, attrs)
{
    this.context=context;
    SetWillNotDraw(false);
    gestureDetector = new GestureDetector(context, new GestureListener());

}

 public override bool OnTouchEvent(MotionEvent e)
{
    Log.Debug(Tag, "Inside" + System.Reflection.MethodBase.GetCurrentMethod().Name + "Method");
    return gestureDetector.OnTouchEvent(e); 
}

private class GestureListener : GestureDetector.SimpleOnGestureListener
{
    public override bool OnDown(MotionEvent e)
    {
        Log.Debug("Tag", "Inside Gesture OnDown Event");
        // don't return false here or else none of the other 
        // gestures will work
        return true;

    }

    public override bool OnSingleTapConfirmed(MotionEvent e)
    {
        Log.Debug("Tag", "Inside Gesture OnSingleTapConfirmed Event");

        return true;
    }

    public override bool OnDoubleTap(MotionEvent e)
    {
        Log.Debug("Tag", "Inside Gesture OnDoubleTap Event");
        return true;
    }

    public override void OnLongPress(MotionEvent e)
    {
        Log.Debug("Tag", "Inside Long Press Event");
    }




}

If you return True in OnDown method all method of GestureListener class will get called except onLongPress()

If you return false in OnDown method then only onLongPress method will get called.

Let me know if my observation is wrong.