FileDocCategorySizeDatePackage
ViewTreeObserver.javaAPI DocAndroid 1.5 API23853Wed May 06 22:41:56 BST 2009android.view

ViewTreeObserver

public final class ViewTreeObserver extends Object
A view tree observer is used to register listeners that can be notified of global changes in the view tree. Such global events include, but are not limited to, layout of the whole tree, beginning of the drawing pass, touch mode change.... A ViewTreeObserver should never be instantiated by applications as it is provided by the views hierarchy. Refer to {@link android.view.View#getViewTreeObserver()} for more information.

Fields Summary
private CopyOnWriteArrayList
mOnGlobalFocusListeners
private CopyOnWriteArrayList
mOnGlobalLayoutListeners
private CopyOnWriteArrayList
mOnPreDrawListeners
private CopyOnWriteArrayList
mOnTouchModeChangeListeners
private CopyOnWriteArrayList
mOnComputeInternalInsetsListeners
private CopyOnWriteArrayList
mOnScrollChangedListeners
private boolean
mAlive
Constructors Summary
ViewTreeObserver()
Creates a new ViewTreeObserver. This constructor should not be called

    
Methods Summary
public voidaddOnComputeInternalInsetsListener(android.view.ViewTreeObserver$OnComputeInternalInsetsListener listener)
Register a callback to be invoked when the invoked when it is time to compute the window's internal insets.

param
listener The callback to add
throws
IllegalStateException If {@link #isAlive()} returns false We are not yet ready to commit to this API and support it, so
hide

        checkIsAlive();

        if (mOnComputeInternalInsetsListeners == null) {
            mOnComputeInternalInsetsListeners =
                    new CopyOnWriteArrayList<OnComputeInternalInsetsListener>();
        }

        mOnComputeInternalInsetsListeners.add(listener);
    
public voidaddOnGlobalFocusChangeListener(android.view.ViewTreeObserver$OnGlobalFocusChangeListener listener)
Register a callback to be invoked when the focus state within the view tree changes.

param
listener The callback to add
throws
IllegalStateException If {@link #isAlive()} returns false

        checkIsAlive();

        if (mOnGlobalFocusListeners == null) {
            mOnGlobalFocusListeners = new CopyOnWriteArrayList<OnGlobalFocusChangeListener>();
        }

        mOnGlobalFocusListeners.add(listener);
    
public voidaddOnGlobalLayoutListener(android.view.ViewTreeObserver$OnGlobalLayoutListener listener)
Register a callback to be invoked when the global layout state or the visibility of views within the view tree changes

param
listener The callback to add
throws
IllegalStateException If {@link #isAlive()} returns false

        checkIsAlive();

        if (mOnGlobalLayoutListeners == null) {
            mOnGlobalLayoutListeners = new CopyOnWriteArrayList<OnGlobalLayoutListener>();
        }

        mOnGlobalLayoutListeners.add(listener);
    
public voidaddOnPreDrawListener(android.view.ViewTreeObserver$OnPreDrawListener listener)
Register a callback to be invoked when the view tree is about to be drawn

param
listener The callback to add
throws
IllegalStateException If {@link #isAlive()} returns false

        checkIsAlive();

        if (mOnPreDrawListeners == null) {
            mOnPreDrawListeners = new CopyOnWriteArrayList<OnPreDrawListener>();
        }

        mOnPreDrawListeners.add(listener);
    
public voidaddOnScrollChangedListener(android.view.ViewTreeObserver$OnScrollChangedListener listener)
Register a callback to be invoked when a view has been scrolled.

param
listener The callback to add
throws
IllegalStateException If {@link #isAlive()} returns false

        checkIsAlive();

        if (mOnScrollChangedListeners == null) {
            mOnScrollChangedListeners = new CopyOnWriteArrayList<OnScrollChangedListener>();
        }

        mOnScrollChangedListeners.add(listener);
    
public voidaddOnTouchModeChangeListener(android.view.ViewTreeObserver$OnTouchModeChangeListener listener)
Register a callback to be invoked when the invoked when the touch mode changes.

param
listener The callback to add
throws
IllegalStateException If {@link #isAlive()} returns false

        checkIsAlive();

        if (mOnTouchModeChangeListeners == null) {
            mOnTouchModeChangeListeners = new CopyOnWriteArrayList<OnTouchModeChangeListener>();
        }

        mOnTouchModeChangeListeners.add(listener);
    
private voidcheckIsAlive()

        if (!mAlive) {
            throw new IllegalStateException("This ViewTreeObserver is not alive, call "
                    + "getViewTreeObserver() again");
        }
    
final voiddispatchOnComputeInternalInsets(android.view.ViewTreeObserver$InternalInsetsInfo inoutInfo)
Calls all listeners to compute the current insets.

        // NOTE: because of the use of CopyOnWriteArrayList, we *must* use an iterator to
        // perform the dispatching. The iterator is a safe guard against listeners that
        // could mutate the list by calling the various add/remove methods. This prevents
        // the array from being modified while we iterate it.
        final CopyOnWriteArrayList<OnComputeInternalInsetsListener> listeners =
                mOnComputeInternalInsetsListeners;
        if (listeners != null) {
            for (OnComputeInternalInsetsListener listener : listeners) {
                listener.onComputeInternalInsets(inoutInfo);
            }
        }
    
final voiddispatchOnGlobalFocusChange(View oldFocus, View newFocus)
Notifies registered listeners that focus has changed.

        // NOTE: because of the use of CopyOnWriteArrayList, we *must* use an iterator to
        // perform the dispatching. The iterator is a safe guard against listeners that
        // could mutate the list by calling the various add/remove methods. This prevents
        // the array from being modified while we iterate it.
        final CopyOnWriteArrayList<OnGlobalFocusChangeListener> listeners = mOnGlobalFocusListeners;
        if (listeners != null) {
            for (OnGlobalFocusChangeListener listener : listeners) {
                listener.onGlobalFocusChanged(oldFocus, newFocus);
            }
        }
    
public final voiddispatchOnGlobalLayout()
Notifies registered listeners that a global layout happened. This can be called manually if you are forcing a layout on a View or a hierarchy of Views that are not attached to a Window or in the GONE state.

        // NOTE: because of the use of CopyOnWriteArrayList, we *must* use an iterator to
        // perform the dispatching. The iterator is a safe guard against listeners that
        // could mutate the list by calling the various add/remove methods. This prevents
        // the array from being modified while we iterate it.
        final CopyOnWriteArrayList<OnGlobalLayoutListener> listeners = mOnGlobalLayoutListeners;
        if (listeners != null) {
            for (OnGlobalLayoutListener listener : listeners) {
                listener.onGlobalLayout();
            }
        }
    
public final booleandispatchOnPreDraw()
Notifies registered listeners that the drawing pass is about to start. If a listener returns true, then the drawing pass is canceled and rescheduled. This can be called manually if you are forcing the drawing on a View or a hierarchy of Views that are not attached to a Window or in the GONE state.

return
True if the current draw should be canceled and resceduled, false otherwise.

        // NOTE: because of the use of CopyOnWriteArrayList, we *must* use an iterator to
        // perform the dispatching. The iterator is a safe guard against listeners that
        // could mutate the list by calling the various add/remove methods. This prevents
        // the array from being modified while we iterate it.
        boolean cancelDraw = false;
        final CopyOnWriteArrayList<OnPreDrawListener> listeners = mOnPreDrawListeners;
        if (listeners != null) {
            for (OnPreDrawListener listener : listeners) {
                cancelDraw |= !listener.onPreDraw();
            }
        }
        return cancelDraw;
    
final voiddispatchOnScrollChanged()
Notifies registered listeners that something has scrolled.

        // NOTE: because of the use of CopyOnWriteArrayList, we *must* use an iterator to
        // perform the dispatching. The iterator is a safe guard against listeners that
        // could mutate the list by calling the various add/remove methods. This prevents
        // the array from being modified while we iterate it.
        final CopyOnWriteArrayList<OnScrollChangedListener> listeners = mOnScrollChangedListeners;
        if (listeners != null) {
            for (OnScrollChangedListener listener : listeners) {
                listener.onScrollChanged();
            }
        }
    
final voiddispatchOnTouchModeChanged(boolean inTouchMode)
Notifies registered listeners that the touch mode has changed.

param
inTouchMode True if the touch mode is now enabled, false otherwise.

        // NOTE: because of the use of CopyOnWriteArrayList, we *must* use an iterator to
        // perform the dispatching. The iterator is a safe guard against listeners that
        // could mutate the list by calling the various add/remove methods. This prevents
        // the array from being modified while we iterate it.
        final CopyOnWriteArrayList<OnTouchModeChangeListener> listeners =
                mOnTouchModeChangeListeners;
        if (listeners != null) {
            for (OnTouchModeChangeListener listener : listeners) {
                listener.onTouchModeChanged(inTouchMode);
            }
        }
    
final booleanhasComputeInternalInsetsListeners()
Returns whether there are listeners for computing internal insets.

        final CopyOnWriteArrayList<OnComputeInternalInsetsListener> listeners =
                mOnComputeInternalInsetsListeners;
        return (listeners != null && listeners.size() > 0);
    
public booleanisAlive()
Indicates whether this ViewTreeObserver is alive. When an observer is not alive, any call to a method (except this one) will throw an exception. If an application keeps a long-lived reference to this ViewTreeObserver, it should always check for the result of this method before calling any other method.

return
True if this object is alive and be used, false otherwise.

        return mAlive;
    
private voidkill()
Marks this ViewTreeObserver as not alive. After invoking this method, invoking any other method but {@link #isAlive()} and {@link #kill()} will throw an Exception.

hide

        mAlive = false;
    
voidmerge(android.view.ViewTreeObserver observer)
Merges all the listeners registered on the specified observer with the listeners registered on this object. After this method is invoked, the specified observer will return false in {@link #isAlive()} and should not be used anymore.

param
observer The ViewTreeObserver whose listeners must be added to this observer

        if (observer.mOnGlobalFocusListeners != null) {
            if (mOnGlobalFocusListeners != null) {
                mOnGlobalFocusListeners.addAll(observer.mOnGlobalFocusListeners);
            } else {
                mOnGlobalFocusListeners = observer.mOnGlobalFocusListeners;
            }
        }

        if (observer.mOnGlobalLayoutListeners != null) {
            if (mOnGlobalLayoutListeners != null) {
                mOnGlobalLayoutListeners.addAll(observer.mOnGlobalLayoutListeners);
            } else {
                mOnGlobalLayoutListeners = observer.mOnGlobalLayoutListeners;
            }
        }

        if (observer.mOnPreDrawListeners != null) {
            if (mOnPreDrawListeners != null) {
                mOnPreDrawListeners.addAll(observer.mOnPreDrawListeners);
            } else {
                mOnPreDrawListeners = observer.mOnPreDrawListeners;
            }
        }

        if (observer.mOnTouchModeChangeListeners != null) {
            if (mOnTouchModeChangeListeners != null) {
                mOnTouchModeChangeListeners.addAll(observer.mOnTouchModeChangeListeners);
            } else {
                mOnTouchModeChangeListeners = observer.mOnTouchModeChangeListeners;
            }
        }

        if (observer.mOnComputeInternalInsetsListeners != null) {
            if (mOnComputeInternalInsetsListeners != null) {
                mOnComputeInternalInsetsListeners.addAll(observer.mOnComputeInternalInsetsListeners);
            } else {
                mOnComputeInternalInsetsListeners = observer.mOnComputeInternalInsetsListeners;
            }
        }

        observer.kill();
    
public voidremoveGlobalOnLayoutListener(android.view.ViewTreeObserver$OnGlobalLayoutListener victim)
Remove a previously installed global layout callback

param
victim The callback to remove
throws
IllegalStateException If {@link #isAlive()} returns false
see
#addOnGlobalLayoutListener(OnGlobalLayoutListener)

        checkIsAlive();
        if (mOnGlobalLayoutListeners == null) {
            return;
        }
        mOnGlobalLayoutListeners.remove(victim);
    
public voidremoveOnComputeInternalInsetsListener(android.view.ViewTreeObserver$OnComputeInternalInsetsListener victim)
Remove a previously installed internal insets computation callback

param
victim The callback to remove
throws
IllegalStateException If {@link #isAlive()} returns false
see
#addOnComputeInternalInsetsListener(OnComputeInternalInsetsListener) We are not yet ready to commit to this API and support it, so
hide

        checkIsAlive();
        if (mOnComputeInternalInsetsListeners == null) {
            return;
        }
        mOnComputeInternalInsetsListeners.remove(victim);
    
public voidremoveOnGlobalFocusChangeListener(android.view.ViewTreeObserver$OnGlobalFocusChangeListener victim)
Remove a previously installed focus change callback.

param
victim The callback to remove
throws
IllegalStateException If {@link #isAlive()} returns false
see
#addOnGlobalFocusChangeListener(OnGlobalFocusChangeListener)

        checkIsAlive();
        if (mOnGlobalFocusListeners == null) {
            return;
        }
        mOnGlobalFocusListeners.remove(victim);
    
public voidremoveOnPreDrawListener(android.view.ViewTreeObserver$OnPreDrawListener victim)
Remove a previously installed pre-draw callback

param
victim The callback to remove
throws
IllegalStateException If {@link #isAlive()} returns false
see
#addOnPreDrawListener(OnPreDrawListener)

        checkIsAlive();
        if (mOnPreDrawListeners == null) {
            return;
        }
        mOnPreDrawListeners.remove(victim);
    
public voidremoveOnScrollChangedListener(android.view.ViewTreeObserver$OnScrollChangedListener victim)
Remove a previously installed scroll-changed callback

param
victim The callback to remove
throws
IllegalStateException If {@link #isAlive()} returns false
see
#addOnScrollChangedListener(OnScrollChangedListener)

        checkIsAlive();
        if (mOnScrollChangedListeners == null) {
            return;
        }
        mOnScrollChangedListeners.remove(victim);
    
public voidremoveOnTouchModeChangeListener(android.view.ViewTreeObserver$OnTouchModeChangeListener victim)
Remove a previously installed touch mode change callback

param
victim The callback to remove
throws
IllegalStateException If {@link #isAlive()} returns false
see
#addOnTouchModeChangeListener(OnTouchModeChangeListener)

        checkIsAlive();
        if (mOnTouchModeChangeListeners == null) {
            return;
        }
        mOnTouchModeChangeListeners.remove(victim);