Listening to Scroll Events on Android Views

What Is the Problem?

While the need to listen to scroll events of arbitrary views in Android has always existed, no such mechanisms were provided by Google until Android API level 23. That is when View.OnScrollChangeListener made its appearance. Until then, some views (e.g. ListView) had custom mechanisms to listen to scroll events, but there was no common way. We at Bugsee have faced this problem while working on automatic concealment of protected web page elements. We had to know when elements change their position, and no such mechanism exists for WebView for earlier Android versions.

The first idea that may come to mind is to extend each class and override the onScrollChanged() method in the subclass. Extending each and every view class doesn’t seem like a very practical thing to do. On top of that, we had to listen to scroll events of an existing WebView instance, passed to Bugsee as a parameter, so that approach was definitely not an option for us.

Luckily, Android SDK provides a way to listen to all scroll type events in the view hierarchy using ViewTreeObserver.OnScrollChangedListener. The class exists since Android API level 3. The inconvenience of this method, however, comes from the fact that ViewTreeObserver might be shared between multiple views, thus further filtering must be done to determine the one that was actually affected. In this article, we will learn to work with ViewTreeObserver.OnScrollChangedListener to encapsulate the complexities while avoiding the common pitfalls.

ListenScrollChangesHelper

Helper Class Interface

Let’s create a helper class for these goals – ListenScrollChangesHelper. This class should have the following public methods.

public class ListenScrollChangesHelper {
    public void addViewToListen(View view, OnScrollChangeListenerCompat listener) {/*…*/}
    public void removeViewToListen(View view) {/*…*/}
    public void clear() {/*…*/}
}

public interface OnScrollChangeListenerCompat {
    void onScrollChange(View v, int scrollX, int scrollY, int oldScrollX, int oldScrollY);
}

For compatibility reasons, OnScrollChangeListenerCompat interface will have the signature of View.OnScrollChangeListener that we are trying to mimic. This will allow us to easily fall back to the native solution if we happen to run on Android API level 23 or later. The clients will register to listen to scroll events of a view by adding it via an addViewToListen() method, while removeViewToListen() will stop monitoring events for that specific view respectively. And call to clear() method stops scroll events listening for all views added before.

Helper Class Implementation

Now, when everything is clear with the interface of this helper, let’s take a look at its implementation.

public class ListenScrollChangesHelper {
    private final WeakHashMap<View, Item> mViewToListenerMap = new WeakHashMap<>();

    @SuppressLint("NewApi")
    public void addViewToListen(View view, OnScrollChangeListenerCompat listener) {
        if (view == null || listener == null)
            return;

        // Fall-back to native solution on newer Android devices.
        if (useNativeScrollChangeListener()) {
            view.setOnScrollChangeListener(new OnScrollChangeListenerAdapter(listener));
            mViewToListenerMap.put(view, null);
            return;
        }

        if (!mViewToListenerMap.containsKey(view)) {
            // Handle case, when previously added view has the same ViewTreeObserver.
            view.getViewTreeObserver().removeOnScrollChangedListener(mObserverOnScrollChangedListener);
            view.getViewTreeObserver().addOnScrollChangedListener(mObserverOnScrollChangedListener);

            view.removeOnLayoutChangeListener(mLayoutChangeListener);
            view.addOnLayoutChangeListener(mLayoutChangeListener);
        }
        Item item = new Item(new Point(view.getScrollX(), view.getScrollY()), listener, view.getViewTreeObserver());
        mViewToListenerMap.put(view, item);
    }

    @SuppressLint("NewApi")
    public void removeViewToListen(View view) {
        if (view == null || mViewToListenerMap.size() == 0)
            return;

        view.removeOnLayoutChangeListener(mLayoutChangeListener);
        if (useNativeScrollChangeListener()) {
            view.setOnScrollChangeListener(null);
        } else if (!haveAnotherViewWithSameObserver(view)) {
            view.getViewTreeObserver().removeOnScrollChangedListener(mObserverOnScrollChangedListener);
        }
        mViewToListenerMap.remove(view);
    }

    public void clear() {
        for (View view : mViewToListenerMap.keySet()) {
            removeViewToListen(view);
        }
    }

    private boolean haveAnotherViewWithSameObserver(View view) {
        for (Map.Entry<View, Item> entry : mViewToListenerMap.entrySet()) {
            if (entry.getKey() != view && entry.getKey().getViewTreeObserver() == view.getViewTreeObserver())
                return true;
        }
        return false;
    }

    // If ViewTreeObserver is not alive, it will throw exception on call to any method except isAlive().
    private static void safeAddOnScrollChangeListener(ViewTreeObserver observer, ViewTreeObserver.OnScrollChangedListener listener) {
        if (observer.isAlive()) {
            observer.addOnScrollChangedListener(listener);
        }
    }

    private static void safeRemoveOnScrollChangeListener(ViewTreeObserver observer, ViewTreeObserver.OnScrollChangedListener listener) {
        if (observer.isAlive()) {
            observer.removeOnScrollChangedListener(listener);
        }
    }

    private static boolean useNativeScrollChangeListener() {
        return (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M);
    }

    private final ViewTreeObserver.OnScrollChangedListener mObserverOnScrollChangedListener = new ViewTreeObserver.OnScrollChangedListener() {
        @Override
        public void onScrollChanged() {
            for (Map.Entry<View, Item> entry : mViewToListenerMap.entrySet()) {
                int scrollX = Math.round(entry.getKey().getScrollX());
                int scrollY = Math.round(entry.getKey().getScrollY());
                int oldScrollX = entry.getValue().ScrollPosition.x;
                int oldScrollY = entry.getValue().ScrollPosition.y;
                if (scrollX != oldScrollX || scrollY != oldScrollY) {
                    entry.getValue().Listener.onScrollChange(entry.getKey(), scrollX, scrollY, oldScrollX, oldScrollY);
                    entry.getValue().ScrollPosition.x = scrollX;
                    entry.getValue().ScrollPosition.y = scrollY;
                }
            }
        }
    };

    // ViewTreeObserver is not guaranteed to remain valid for the lifetime of view.
    private final View.OnLayoutChangeListener mLayoutChangeListener = new View.OnLayoutChangeListener() {
        @Override
        public void onLayoutChange(View view, int left, int top, int right, int bottom, int oldLeft, int oldTop, int oldRight, int oldBottom) {
            Item item = mViewToListenerMap.get(view);
            if (item == null)
                return;

            if (item.Observer != view.getViewTreeObserver()) {
                safeRemoveOnScrollChangeListener(item.Observer, mObserverOnScrollChangedListener);

                item.Observer = view.getViewTreeObserver();
                safeAddOnScrollChangeListener(item.Observer, mObserverOnScrollChangedListener);
            }
        }
    };

    private static class Item {
        Point ScrollPosition;
        OnScrollChangeListenerCompat Listener;
        ViewTreeObserver Observer;

        public Item(Point scrollPosition, OnScrollChangeListenerCompat listener, ViewTreeObserver observer) {
            ScrollPosition = scrollPosition;
            Listener = listener;
            Observer = observer;
        }
    }
}

We use WeakHashMap instead of HashMap to avoid potential memory leaks. View has back reference to its activity, thus using strong references might prevent the whole activity from being garbage collected.

In the addViewToListen() method we check the device API level and if it is at least 23, use native View.OnScrollChangeListener, wrapping OnScrollChangeListenerCompat in simple adapter OnScrollChangeListenerAdapter. When possible, it is always preferred to use the native mechanism as it might be better optimized and thus decrease computational overhead.

@RequiresApi(api = Build.VERSION_CODES.M)
public class OnScrollChangeListenerAdapter implements View.OnScrollChangeListener {
    private final OnScrollChangeListenerCompat mOnScrollChangeListener;

    public OnScrollChangeListenerAdapter(OnScrollChangeListenerCompat onScrollChangeListener) {
        mOnScrollChangeListener = onScrollChangeListener;
    }

    @Override
    public void onScrollChange(View v, int scrollX, int scrollY, int oldScrollX, int oldScrollY) {
        mOnScrollChangeListener.onScrollChange(v, scrollX, scrollY, oldScrollX, oldScrollY);
    }
}

On devices with a lower API level, we add the listener to the ViewTreeObserver of the monitored view. Note, that we call removeOnScrollChangedListener() prior to calling addOnScrollListener(). It is a common practice when adding listeners, which helps avoid adding the same listener twice. In our case, it's a real possibility, as two monitored views might share the same ViewTreeObserver.

Within the ViewTreeObserver.OnScrollChangedListener’s onScrollChanged() method we iterate over the monitored views, find the one that actually scrolled and notify only the listener of that particular view.

Since ViewTreeObserver is not guaranteed to remain valid for the lifetime of a view, we check it and update if necessary in view’s OnLayoutChangeListener. One more thing to take into account is that ViewTreeObserver, which is not alive, will throw an exception on call to any method except isAlive(). Methods safeAddOnScrollChangeListener() and safeRemoveOnScrollChangeListener() help to deal with this problem by first checking isAlive() method result.

In this tutorial, we’ve created a generic mechanism for listening to scroll events from any view, that works on a wide variety of Android API levels.

The full source code, along with a sample project that demonstrates the functionality, is hosted on GitHub. Feel free to download and try it yourself.

The sample project contains one activity with WebView and Listen/Stop listening buttons which start and stop monitoring for WebView scroll events respectively.