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.