/* * Copyright (C) 2013 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.support.v7.widget; import android.content.Context; import android.database.Observable; import android.graphics.Canvas; import android.graphics.PointF; import android.graphics.Rect; import android.os.Build; import android.os.Parcel; import android.os.Parcelable; import android.support.annotation.Nullable; import android.support.v4.util.ArrayMap; import android.support.v4.view.MotionEventCompat; import android.support.v4.view.VelocityTrackerCompat; import android.support.v4.view.ViewCompat; import android.support.v4.widget.EdgeEffectCompat; import android.support.v4.widget.ScrollerCompat; import static android.support.v7.widget.AdapterHelper.UpdateOp; import static android.support.v7.widget.AdapterHelper.Callback; import android.util.AttributeSet; import android.util.Log; import android.util.SparseArray; import android.util.SparseIntArray; import android.view.FocusFinder; import android.view.MotionEvent; import android.view.VelocityTracker; import android.view.View; import android.view.ViewConfiguration; import android.view.ViewGroup; import android.view.ViewParent; import android.view.animation.Interpolator; import java.util.ArrayList; import java.util.Collections; import java.util.List; /** * A flexible view for providing a limited window into a large data set. * *
This listener will be called when a LayoutManager or the RecyclerView decides * that a child view is no longer needed. If an application associates expensive * or heavyweight data with item views, this may be a good place to release * or free those resources.
* * @param listener Listener to register, or null to clear */ public void setRecyclerListener(RecyclerListener listener) { mRecyclerListener = listener; } /** * Set the {@link LayoutManager} that this RecyclerView will use. * *In contrast to other adapter-backed views such as {@link android.widget.ListView} * or {@link android.widget.GridView}, RecyclerView allows client code to provide custom * layout arrangements for child views. These arrangements are controlled by the * {@link LayoutManager}. A LayoutManager must be provided for RecyclerView to function.
* *Several default strategies are provided for common uses such as lists and grids.
* * @param layout LayoutManager to use */ public void setLayoutManager(LayoutManager layout) { if (layout == mLayout) { return; } // TODO We should do this switch a dispachLayout pass and animate children. There is a good // chance that LayoutManagers will re-use views. if (mLayout != null) { if (mIsAttached) { mLayout.onDetachedFromWindow(this, mRecycler); } mLayout.setRecyclerView(null); } mRecycler.clear(); mChildHelper.removeAllViewsUnfiltered(); mLayout = layout; if (layout != null) { if (layout.mRecyclerView != null) { throw new IllegalArgumentException("LayoutManager " + layout + " is already attached to a RecyclerView: " + layout.mRecyclerView); } mLayout.setRecyclerView(this); if (mIsAttached) { mLayout.onAttachedToWindow(this); } } requestLayout(); } @Override protected Parcelable onSaveInstanceState() { SavedState state = new SavedState(super.onSaveInstanceState()); if (mPendingSavedState != null) { state.copyFrom(mPendingSavedState); } else if (mLayout != null) { state.mLayoutState = mLayout.onSaveInstanceState(); } else { state.mLayoutState = null; } return state; } @Override protected void onRestoreInstanceState(Parcelable state) { mPendingSavedState = (SavedState) state; super.onRestoreInstanceState(mPendingSavedState.getSuperState()); if (mLayout != null && mPendingSavedState.mLayoutState != null) { mLayout.onRestoreInstanceState(mPendingSavedState.mLayoutState); } } /** * Adds a view to the animatingViews list. * mAnimatingViews holds the child views that are currently being kept around * purely for the purpose of being animated out of view. They are drawn as a regular * part of the child list of the RecyclerView, but they are invisible to the LayoutManager * as they are managed separately from the regular child views. * @param view The view to be removed */ private void addAnimatingView(View view) { final boolean alreadyParented = view.getParent() == this; mRecycler.unscrapView(getChildViewHolder(view)); if (!alreadyParented) { mChildHelper.addView(view, true); } else { mChildHelper.hide(view); } } /** * Removes a view from the animatingViews list. * @param view The view to be removed * @see #addAnimatingView(View) */ private void removeAnimatingView(View view) { eatRequestLayout(); if (mChildHelper.removeViewIfHidden(view)) { mRecycler.unscrapView(getChildViewHolderInt(view)); mRecycler.recycleView(view); if (DEBUG) { Log.d(TAG, "after removing animated view: " + view + ", " + this); } } resumeRequestLayout(false); } /** * Return the {@link LayoutManager} currently responsible for * layout policy for this RecyclerView. * * @return The currently bound LayoutManager */ public LayoutManager getLayoutManager() { return mLayout; } /** * Retrieve this RecyclerView's {@link RecycledViewPool}. This method will never return null; * if no pool is set for this view a new one will be created. See * {@link #setRecycledViewPool(RecycledViewPool) setRecycledViewPool} for more information. * * @return The pool used to store recycled item views for reuse. * @see #setRecycledViewPool(RecycledViewPool) */ public RecycledViewPool getRecycledViewPool() { return mRecycler.getRecycledViewPool(); } /** * Recycled view pools allow multiple RecyclerViews to share a common pool of scrap views. * This can be useful if you have multiple RecyclerViews with adapters that use the same * view types, for example if you have several data sets with the same kinds of item views * displayed by a {@link android.support.v4.view.ViewPager ViewPager}. * * @param pool Pool to set. If this parameter is null a new pool will be created and used. */ public void setRecycledViewPool(RecycledViewPool pool) { mRecycler.setRecycledViewPool(pool); } /** * Sets a new {@link ViewCacheExtension} to be used by the Recycler. * * @param extension ViewCacheExtension to be used or null if you want to clear the existing one. * * @see {@link ViewCacheExtension#getViewForPositionAndType(Recycler, int, int)} */ public void setViewCacheExtension(ViewCacheExtension extension) { mRecycler.setViewCacheExtension(extension); } /** * Set the number of offscreen views to retain before adding them to the potentially shared * {@link #getRecycledViewPool() recycled view pool}. * *The offscreen view cache stays aware of changes in the attached adapter, allowing * a LayoutManager to reuse those views unmodified without needing to return to the adapter * to rebind them.
* * @param size Number of views to cache offscreen before returning them to the general * recycled view pool */ public void setItemViewCacheSize(int size) { mRecycler.setViewCacheSize(size); } /** * Return the current scrolling state of the RecyclerView. * * @return {@link #SCROLL_STATE_IDLE}, {@link #SCROLL_STATE_DRAGGING} or * {@link #SCROLL_STATE_SETTLING} */ public int getScrollState() { return mScrollState; } private void setScrollState(int state) { if (state == mScrollState) { return; } mScrollState = state; if (state != SCROLL_STATE_SETTLING) { stopScroll(); } if (mScrollListener != null) { mScrollListener.onScrollStateChanged(state); } mLayout.onScrollStateChanged(state); } /** * Add an {@link ItemDecoration} to this RecyclerView. Item decorations can * affect both measurement and drawing of individual item views. * *Item decorations are ordered. Decorations placed earlier in the list will * be run/queried/drawn first for their effects on item views. Padding added to views * will be nested; a padding added by an earlier decoration will mean further * item decorations in the list will be asked to draw/pad within the previous decoration's * given area.
* * @param decor Decoration to add * @param index Position in the decoration chain to insert this decoration at. If this value * is negative the decoration will be added at the end. */ public void addItemDecoration(ItemDecoration decor, int index) { if (mItemDecorations.isEmpty()) { setWillNotDraw(false); } if (index < 0) { mItemDecorations.add(decor); } else { mItemDecorations.add(index, decor); } markItemDecorInsetsDirty(); requestLayout(); } /** * Add an {@link ItemDecoration} to this RecyclerView. Item decorations can * affect both measurement and drawing of individual item views. * *Item decorations are ordered. Decorations placed earlier in the list will * be run/queried/drawn first for their effects on item views. Padding added to views * will be nested; a padding added by an earlier decoration will mean further * item decorations in the list will be asked to draw/pad within the previous decoration's * given area.
* * @param decor Decoration to add */ public void addItemDecoration(ItemDecoration decor) { addItemDecoration(decor, -1); } /** * Remove an {@link ItemDecoration} from this RecyclerView. * *The given decoration will no longer impact the measurement and drawing of * item views.
* * @param decor Decoration to remove * @see #addItemDecoration(ItemDecoration) */ public void removeItemDecoration(ItemDecoration decor) { mItemDecorations.remove(decor); if (mItemDecorations.isEmpty()) { setWillNotDraw(ViewCompat.getOverScrollMode(this) == ViewCompat.OVER_SCROLL_NEVER); } markItemDecorInsetsDirty(); requestLayout(); } /** * Set a listener that will be notified of any changes in scroll state or position. * * @param listener Listener to set or null to clear */ public void setOnScrollListener(OnScrollListener listener) { mScrollListener = listener; } /** * Convenience method to scroll to a certain position. * * RecyclerView does not implement scrolling logic, rather forwards the call to * {@link android.support.v7.widget.RecyclerView.LayoutManager#scrollToPosition(int)} * @param position Scroll to this adapter position * @see android.support.v7.widget.RecyclerView.LayoutManager#scrollToPosition(int) */ public void scrollToPosition(int position) { stopScroll(); mLayout.scrollToPosition(position); awakenScrollBars(); } /** * Starts a smooth scroll to an adapter position. ** To support smooth scrolling, you must override * {@link LayoutManager#smoothScrollToPosition(RecyclerView, State, int)} and create a * {@link SmoothScroller}. *
* {@link LayoutManager} is responsible for creating the actual scroll action. If you want to * provide a custom smooth scroll logic, override * {@link LayoutManager#smoothScrollToPosition(RecyclerView, State, int)} in your * LayoutManager. * * @param position The adapter position to scroll to * @see LayoutManager#smoothScrollToPosition(RecyclerView, State, int) */ public void smoothScrollToPosition(int position) { mLayout.smoothScrollToPosition(this, mState, position); } @Override public void scrollTo(int x, int y) { throw new UnsupportedOperationException( "RecyclerView does not support scrolling to an absolute position."); } @Override public void scrollBy(int x, int y) { if (mLayout == null) { throw new IllegalStateException("Cannot scroll without a LayoutManager set. " + "Call setLayoutManager with a non-null argument."); } final boolean canScrollHorizontal = mLayout.canScrollHorizontally(); final boolean canScrollVertical = mLayout.canScrollVertically(); if (canScrollHorizontal || canScrollVertical) { scrollByInternal(canScrollHorizontal ? x : 0, canScrollVertical ? y : 0); } } /** * Helper method reflect data changes to the state. *
* Adapter changes during a scroll may trigger a crash because scroll assumes no data change * but data actually changed. *
* This method consumes all deferred changes to avoid that case. */ private void consumePendingUpdateOperations() { if (mAdapterHelper.hasPendingUpdates()) { mUpdateChildViewsRunnable.run(); } } /** * Does not perform bounds checking. Used by internal methods that have already validated input. */ void scrollByInternal(int x, int y) { int overscrollX = 0, overscrollY = 0; consumePendingUpdateOperations(); if (mAdapter != null) { eatRequestLayout(); mRunningLayoutOrScroll = true; if (x != 0) { final int hresult = mLayout.scrollHorizontallyBy(x, mRecycler, mState); overscrollX = x - hresult; } if (y != 0) { final int vresult = mLayout.scrollVerticallyBy(y, mRecycler, mState); overscrollY = y - vresult; } if (supportsChangeAnimations()) { // Fix up shadow views used by changing animations int count = mChildHelper.getChildCount(); for (int i = 0; i < count; i++) { View view = mChildHelper.getChildAt(i); ViewHolder holder = getChildViewHolder(view); if (holder != null && holder.mShadowingHolder != null) { ViewHolder shadowingHolder = holder.mShadowingHolder; View shadowingView = shadowingHolder != null ? shadowingHolder.itemView : null; if (shadowingView != null) { int left = view.getLeft(); int top = view.getTop(); if (left != shadowingView.getLeft() || top != shadowingView.getTop()) { shadowingView.layout(left, top, left + shadowingView.getWidth(), top + shadowingView.getHeight()); } } } } } mRunningLayoutOrScroll = false; resumeRequestLayout(false); } if (!mItemDecorations.isEmpty()) { invalidate(); } if (ViewCompat.getOverScrollMode(this) != ViewCompat.OVER_SCROLL_NEVER) { considerReleasingGlowsOnScroll(x, y); pullGlows(overscrollX, overscrollY); } if (mScrollListener != null && (x != 0 || y != 0)) { mScrollListener.onScrolled(x, y); } if (!awakenScrollBars()) { invalidate(); } } /** *
Compute the horizontal offset of the horizontal scrollbar's thumb within the horizontal * range. This value is used to compute the length of the thumb within the scrollbar's track. *
* *The range is expressed in arbitrary units that must be the same as the units used by * {@link #computeHorizontalScrollRange()} and {@link #computeHorizontalScrollExtent()}.
* *Default implementation returns 0.
* *If you want to support scroll bars, override * {@link RecyclerView.LayoutManager#computeHorizontalScrollOffset(RecyclerView.State)} in your * LayoutManager.
* * @return The horizontal offset of the scrollbar's thumb * @see android.support.v7.widget.RecyclerView.LayoutManager#computeHorizontalScrollOffset * (RecyclerView.Adapter) */ @Override protected int computeHorizontalScrollOffset() { return mLayout.canScrollHorizontally() ? mLayout.computeHorizontalScrollOffset(mState) : 0; } /** *Compute the horizontal extent of the horizontal scrollbar's thumb within the * horizontal range. This value is used to compute the length of the thumb within the * scrollbar's track.
* *The range is expressed in arbitrary units that must be the same as the units used by * {@link #computeHorizontalScrollRange()} and {@link #computeHorizontalScrollOffset()}.
* *Default implementation returns 0.
* *If you want to support scroll bars, override * {@link RecyclerView.LayoutManager#computeHorizontalScrollExtent(RecyclerView.State)} in your * LayoutManager.
* * @return The horizontal extent of the scrollbar's thumb * @see RecyclerView.LayoutManager#computeHorizontalScrollExtent(RecyclerView.State) */ @Override protected int computeHorizontalScrollExtent() { return mLayout.canScrollHorizontally() ? mLayout.computeHorizontalScrollExtent(mState) : 0; } /** *Compute the horizontal range that the horizontal scrollbar represents.
* *The range is expressed in arbitrary units that must be the same as the units used by * {@link #computeHorizontalScrollExtent()} and {@link #computeHorizontalScrollOffset()}.
* *Default implementation returns 0.
* *If you want to support scroll bars, override * {@link RecyclerView.LayoutManager#computeHorizontalScrollRange(RecyclerView.State)} in your * LayoutManager.
* * @return The total horizontal range represented by the vertical scrollbar * @see RecyclerView.LayoutManager#computeHorizontalScrollRange(RecyclerView.State) */ @Override protected int computeHorizontalScrollRange() { return mLayout.canScrollHorizontally() ? mLayout.computeHorizontalScrollRange(mState) : 0; } /** *Compute the vertical offset of the vertical scrollbar's thumb within the vertical range. * This value is used to compute the length of the thumb within the scrollbar's track.
* *The range is expressed in arbitrary units that must be the same as the units used by * {@link #computeVerticalScrollRange()} and {@link #computeVerticalScrollExtent()}.
* *Default implementation returns 0.
* *If you want to support scroll bars, override * {@link RecyclerView.LayoutManager#computeVerticalScrollOffset(RecyclerView.State)} in your * LayoutManager.
* * @return The vertical offset of the scrollbar's thumb * @see android.support.v7.widget.RecyclerView.LayoutManager#computeVerticalScrollOffset * (RecyclerView.Adapter) */ @Override protected int computeVerticalScrollOffset() { return mLayout.canScrollVertically() ? mLayout.computeVerticalScrollOffset(mState) : 0; } /** *Compute the vertical extent of the vertical scrollbar's thumb within the vertical range. * This value is used to compute the length of the thumb within the scrollbar's track.
* *The range is expressed in arbitrary units that must be the same as the units used by * {@link #computeVerticalScrollRange()} and {@link #computeVerticalScrollOffset()}.
* *Default implementation returns 0.
* *If you want to support scroll bars, override * {@link RecyclerView.LayoutManager#computeVerticalScrollExtent(RecyclerView.State)} in your * LayoutManager.
* * @return The vertical extent of the scrollbar's thumb * @see RecyclerView.LayoutManager#computeVerticalScrollExtent(RecyclerView.State) */ @Override protected int computeVerticalScrollExtent() { return mLayout.canScrollVertically() ? mLayout.computeVerticalScrollExtent(mState) : 0; } /** *Compute the vertical range that the vertical scrollbar represents.
* *The range is expressed in arbitrary units that must be the same as the units used by * {@link #computeVerticalScrollExtent()} and {@link #computeVerticalScrollOffset()}.
* *Default implementation returns 0.
* *If you want to support scroll bars, override * {@link RecyclerView.LayoutManager#computeVerticalScrollRange(RecyclerView.State)} in your * LayoutManager.
* * @return The total vertical range represented by the vertical scrollbar * @see RecyclerView.LayoutManager#computeVerticalScrollRange(RecyclerView.State) */ @Override protected int computeVerticalScrollRange() { return mLayout.canScrollVertically() ? mLayout.computeVerticalScrollRange(mState) : 0; } void eatRequestLayout() { if (!mEatRequestLayout) { mEatRequestLayout = true; mLayoutRequestEaten = false; } } void resumeRequestLayout(boolean performLayoutChildren) { if (mEatRequestLayout) { if (performLayoutChildren && mLayoutRequestEaten && mLayout != null && mAdapter != null) { dispatchLayout(); } mEatRequestLayout = false; mLayoutRequestEaten = false; } } /** * Animate a scroll by the given amount of pixels along either axis. * * @param dx Pixels to scroll horizontally * @param dy Pixels to scroll vertically */ public void smoothScrollBy(int dx, int dy) { if (dx != 0 || dy != 0) { mViewFlinger.smoothScrollBy(dx, dy); } } /** * Begin a standard fling with an initial velocity along each axis in pixels per second. * If the velocity given is below the system-defined minimum this method will return false * and no fling will occur. * * @param velocityX Initial horizontal velocity in pixels per second * @param velocityY Initial vertical velocity in pixels per second * @return true if the fling was started, false if the velocity was too low to fling */ public boolean fling(int velocityX, int velocityY) { if (Math.abs(velocityX) < mMinFlingVelocity) { velocityX = 0; } if (Math.abs(velocityY) < mMinFlingVelocity) { velocityY = 0; } velocityX = Math.max(-mMaxFlingVelocity, Math.min(velocityX, mMaxFlingVelocity)); velocityY = Math.max(-mMaxFlingVelocity, Math.min(velocityY, mMaxFlingVelocity)); if (velocityX != 0 || velocityY != 0) { mViewFlinger.fling(velocityX, velocityY); return true; } return false; } /** * Stop any current scroll in progress, such as one started by * {@link #smoothScrollBy(int, int)}, {@link #fling(int, int)} or a touch-initiated fling. */ public void stopScroll() { mViewFlinger.stop(); mLayout.stopSmoothScroller(); } /** * Apply a pull to relevant overscroll glow effects */ private void pullGlows(int overscrollX, int overscrollY) { if (overscrollX < 0) { if (mLeftGlow == null) { mLeftGlow = new EdgeEffectCompat(getContext()); mLeftGlow.setSize(getMeasuredHeight() - getPaddingTop() - getPaddingBottom(), getMeasuredWidth() - getPaddingLeft() - getPaddingRight()); } mLeftGlow.onPull(-overscrollX / (float) getWidth()); } else if (overscrollX > 0) { if (mRightGlow == null) { mRightGlow = new EdgeEffectCompat(getContext()); mRightGlow.setSize(getMeasuredHeight() - getPaddingTop() - getPaddingBottom(), getMeasuredWidth() - getPaddingLeft() - getPaddingRight()); } mRightGlow.onPull(overscrollX / (float) getWidth()); } if (overscrollY < 0) { if (mTopGlow == null) { mTopGlow = new EdgeEffectCompat(getContext()); mTopGlow.setSize(getMeasuredWidth() - getPaddingLeft() - getPaddingRight(), getMeasuredHeight() - getPaddingTop() - getPaddingBottom()); } mTopGlow.onPull(-overscrollY / (float) getHeight()); } else if (overscrollY > 0) { if (mBottomGlow == null) { mBottomGlow = new EdgeEffectCompat(getContext()); mBottomGlow.setSize(getMeasuredWidth() - getPaddingLeft() - getPaddingRight(), getMeasuredHeight() - getPaddingTop() - getPaddingBottom()); } mBottomGlow.onPull(overscrollY / (float) getHeight()); } if (overscrollX != 0 || overscrollY != 0) { ViewCompat.postInvalidateOnAnimation(this); } } private void releaseGlows() { boolean needsInvalidate = false; if (mLeftGlow != null) needsInvalidate = mLeftGlow.onRelease(); if (mTopGlow != null) needsInvalidate |= mTopGlow.onRelease(); if (mRightGlow != null) needsInvalidate |= mRightGlow.onRelease(); if (mBottomGlow != null) needsInvalidate |= mBottomGlow.onRelease(); if (needsInvalidate) { ViewCompat.postInvalidateOnAnimation(this); } } private void considerReleasingGlowsOnScroll(int dx, int dy) { boolean needsInvalidate = false; if (mLeftGlow != null && !mLeftGlow.isFinished() && dx > 0) { needsInvalidate = mLeftGlow.onRelease(); } if (mRightGlow != null && !mRightGlow.isFinished() && dx < 0) { needsInvalidate |= mRightGlow.onRelease(); } if (mTopGlow != null && !mTopGlow.isFinished() && dy > 0) { needsInvalidate |= mTopGlow.onRelease(); } if (mBottomGlow != null && !mBottomGlow.isFinished() && dy < 0) { needsInvalidate |= mBottomGlow.onRelease(); } if (needsInvalidate) { ViewCompat.postInvalidateOnAnimation(this); } } void absorbGlows(int velocityX, int velocityY) { if (velocityX < 0) { if (mLeftGlow == null) { mLeftGlow = new EdgeEffectCompat(getContext()); mLeftGlow.setSize(getMeasuredHeight() - getPaddingTop() - getPaddingBottom(), getMeasuredWidth() - getPaddingLeft() - getPaddingRight()); } mLeftGlow.onAbsorb(-velocityX); } else if (velocityX > 0) { if (mRightGlow == null) { mRightGlow = new EdgeEffectCompat(getContext()); mRightGlow.setSize(getMeasuredHeight() - getPaddingTop() - getPaddingBottom(), getMeasuredWidth() - getPaddingLeft() - getPaddingRight()); } mRightGlow.onAbsorb(velocityX); } if (velocityY < 0) { if (mTopGlow == null) { mTopGlow = new EdgeEffectCompat(getContext()); mTopGlow.setSize(getMeasuredWidth() - getPaddingLeft() - getPaddingRight(), getMeasuredHeight() - getPaddingTop() - getPaddingBottom()); } mTopGlow.onAbsorb(-velocityY); } else if (velocityY > 0) { if (mBottomGlow == null) { mBottomGlow = new EdgeEffectCompat(getContext()); mBottomGlow.setSize(getMeasuredWidth() - getPaddingLeft() - getPaddingRight(), getMeasuredHeight() - getPaddingTop() - getPaddingBottom()); } mBottomGlow.onAbsorb(velocityY); } if (velocityX != 0 || velocityY != 0) { ViewCompat.postInvalidateOnAnimation(this); } } // Focus handling @Override public View focusSearch(View focused, int direction) { View result = mLayout.onInterceptFocusSearch(focused, direction); if (result != null) { return result; } final FocusFinder ff = FocusFinder.getInstance(); result = ff.findNextFocus(this, focused, direction); if (result == null && mAdapter != null) { eatRequestLayout(); result = mLayout.onFocusSearchFailed(focused, direction, mRecycler, mState); resumeRequestLayout(false); } return result != null ? result : super.focusSearch(focused, direction); } @Override public void requestChildFocus(View child, View focused) { if (!mLayout.onRequestChildFocus(this, mState, child, focused)) { mTempRect.set(0, 0, focused.getWidth(), focused.getHeight()); offsetDescendantRectToMyCoords(focused, mTempRect); offsetRectIntoDescendantCoords(child, mTempRect); requestChildRectangleOnScreen(child, mTempRect, !mFirstLayoutComplete); } super.requestChildFocus(child, focused); } @Override public boolean requestChildRectangleOnScreen(View child, Rect rect, boolean immediate) { return mLayout.requestChildRectangleOnScreen(this, child, rect, immediate); } @Override public void addFocusables(ArrayListClient code may use listeners to implement item manipulation behavior. Once a listener * returns true from * {@link OnItemTouchListener#onInterceptTouchEvent(RecyclerView, MotionEvent)} its * {@link OnItemTouchListener#onTouchEvent(RecyclerView, MotionEvent)} method will be called * for each incoming MotionEvent until the end of the gesture.
* * @param listener Listener to add */ public void addOnItemTouchListener(OnItemTouchListener listener) { mOnItemTouchListeners.add(listener); } /** * Remove an {@link OnItemTouchListener}. It will no longer be able to intercept touch events. * * @param listener Listener to remove */ public void removeOnItemTouchListener(OnItemTouchListener listener) { mOnItemTouchListeners.remove(listener); if (mActiveOnItemTouchListener == listener) { mActiveOnItemTouchListener = null; } } private boolean dispatchOnItemTouchIntercept(MotionEvent e) { final int action = e.getAction(); if (action == MotionEvent.ACTION_CANCEL || action == MotionEvent.ACTION_DOWN) { mActiveOnItemTouchListener = null; } final int listenerCount = mOnItemTouchListeners.size(); for (int i = 0; i < listenerCount; i++) { final OnItemTouchListener listener = mOnItemTouchListeners.get(i); if (listener.onInterceptTouchEvent(this, e) && action != MotionEvent.ACTION_CANCEL) { mActiveOnItemTouchListener = listener; return true; } } return false; } private boolean dispatchOnItemTouch(MotionEvent e) { final int action = e.getAction(); if (mActiveOnItemTouchListener != null) { if (action == MotionEvent.ACTION_DOWN) { // Stale state from a previous gesture, we're starting a new one. Clear it. mActiveOnItemTouchListener = null; } else { mActiveOnItemTouchListener.onTouchEvent(this, e); if (action == MotionEvent.ACTION_CANCEL || action == MotionEvent.ACTION_UP) { // Clean up for the next gesture. mActiveOnItemTouchListener = null; } return true; } } // Listeners will have already received the ACTION_DOWN via dispatchOnItemTouchIntercept // as called from onInterceptTouchEvent; skip it. if (action != MotionEvent.ACTION_DOWN) { final int listenerCount = mOnItemTouchListeners.size(); for (int i = 0; i < listenerCount; i++) { final OnItemTouchListener listener = mOnItemTouchListeners.get(i); if (listener.onInterceptTouchEvent(this, e)) { mActiveOnItemTouchListener = listener; return true; } } } return false; } @Override public boolean onInterceptTouchEvent(MotionEvent e) { if (dispatchOnItemTouchIntercept(e)) { cancelTouch(); return true; } final boolean canScrollHorizontally = mLayout.canScrollHorizontally(); final boolean canScrollVertically = mLayout.canScrollVertically(); if (mVelocityTracker == null) { mVelocityTracker = VelocityTracker.obtain(); } mVelocityTracker.addMovement(e); final int action = MotionEventCompat.getActionMasked(e); final int actionIndex = MotionEventCompat.getActionIndex(e); switch (action) { case MotionEvent.ACTION_DOWN: mScrollPointerId = MotionEventCompat.getPointerId(e, 0); mInitialTouchX = mLastTouchX = (int) (e.getX() + 0.5f); mInitialTouchY = mLastTouchY = (int) (e.getY() + 0.5f); if (mScrollState == SCROLL_STATE_SETTLING) { getParent().requestDisallowInterceptTouchEvent(true); setScrollState(SCROLL_STATE_DRAGGING); } break; case MotionEventCompat.ACTION_POINTER_DOWN: mScrollPointerId = MotionEventCompat.getPointerId(e, actionIndex); mInitialTouchX = mLastTouchX = (int) (MotionEventCompat.getX(e, actionIndex) + 0.5f); mInitialTouchY = mLastTouchY = (int) (MotionEventCompat.getY(e, actionIndex) + 0.5f); break; case MotionEvent.ACTION_MOVE: { final int index = MotionEventCompat.findPointerIndex(e, mScrollPointerId); if (index < 0) { Log.e(TAG, "Error processing scroll; pointer index for id " + mScrollPointerId + " not found. Did any MotionEvents get skipped?"); return false; } final int x = (int) (MotionEventCompat.getX(e, index) + 0.5f); final int y = (int) (MotionEventCompat.getY(e, index) + 0.5f); if (mScrollState != SCROLL_STATE_DRAGGING) { final int dx = x - mInitialTouchX; final int dy = y - mInitialTouchY; boolean startScroll = false; if (canScrollHorizontally && Math.abs(dx) > mTouchSlop) { mLastTouchX = mInitialTouchX + mTouchSlop * (dx < 0 ? -1 : 1); startScroll = true; } if (canScrollVertically && Math.abs(dy) > mTouchSlop) { mLastTouchY = mInitialTouchY + mTouchSlop * (dy < 0 ? -1 : 1); startScroll = true; } if (startScroll) { getParent().requestDisallowInterceptTouchEvent(true); setScrollState(SCROLL_STATE_DRAGGING); } } } break; case MotionEventCompat.ACTION_POINTER_UP: { onPointerUp(e); } break; case MotionEvent.ACTION_UP: { mVelocityTracker.clear(); } break; case MotionEvent.ACTION_CANCEL: { cancelTouch(); } } return mScrollState == SCROLL_STATE_DRAGGING; } @Override public boolean onTouchEvent(MotionEvent e) { if (dispatchOnItemTouch(e)) { cancelTouch(); return true; } final boolean canScrollHorizontally = mLayout.canScrollHorizontally(); final boolean canScrollVertically = mLayout.canScrollVertically(); if (mVelocityTracker == null) { mVelocityTracker = VelocityTracker.obtain(); } mVelocityTracker.addMovement(e); final int action = MotionEventCompat.getActionMasked(e); final int actionIndex = MotionEventCompat.getActionIndex(e); switch (action) { case MotionEvent.ACTION_DOWN: { mScrollPointerId = MotionEventCompat.getPointerId(e, 0); mInitialTouchX = mLastTouchX = (int) (e.getX() + 0.5f); mInitialTouchY = mLastTouchY = (int) (e.getY() + 0.5f); } break; case MotionEventCompat.ACTION_POINTER_DOWN: { mScrollPointerId = MotionEventCompat.getPointerId(e, actionIndex); mInitialTouchX = mLastTouchX = (int) (MotionEventCompat.getX(e, actionIndex) + 0.5f); mInitialTouchY = mLastTouchY = (int) (MotionEventCompat.getY(e, actionIndex) + 0.5f); } break; case MotionEvent.ACTION_MOVE: { final int index = MotionEventCompat.findPointerIndex(e, mScrollPointerId); if (index < 0) { Log.e(TAG, "Error processing scroll; pointer index for id " + mScrollPointerId + " not found. Did any MotionEvents get skipped?"); return false; } final int x = (int) (MotionEventCompat.getX(e, index) + 0.5f); final int y = (int) (MotionEventCompat.getY(e, index) + 0.5f); if (mScrollState != SCROLL_STATE_DRAGGING) { final int dx = x - mInitialTouchX; final int dy = y - mInitialTouchY; boolean startScroll = false; if (canScrollHorizontally && Math.abs(dx) > mTouchSlop) { mLastTouchX = mInitialTouchX + mTouchSlop * (dx < 0 ? -1 : 1); startScroll = true; } if (canScrollVertically && Math.abs(dy) > mTouchSlop) { mLastTouchY = mInitialTouchY + mTouchSlop * (dy < 0 ? -1 : 1); startScroll = true; } if (startScroll) { getParent().requestDisallowInterceptTouchEvent(true); setScrollState(SCROLL_STATE_DRAGGING); } } if (mScrollState == SCROLL_STATE_DRAGGING) { final int dx = x - mLastTouchX; final int dy = y - mLastTouchY; scrollByInternal(canScrollHorizontally ? -dx : 0, canScrollVertically ? -dy : 0); } mLastTouchX = x; mLastTouchY = y; } break; case MotionEventCompat.ACTION_POINTER_UP: { onPointerUp(e); } break; case MotionEvent.ACTION_UP: { mVelocityTracker.computeCurrentVelocity(1000, mMaxFlingVelocity); final float xvel = canScrollHorizontally ? -VelocityTrackerCompat.getXVelocity(mVelocityTracker, mScrollPointerId) : 0; final float yvel = canScrollVertically ? -VelocityTrackerCompat.getYVelocity(mVelocityTracker, mScrollPointerId) : 0; if (!((xvel != 0 || yvel != 0) && fling((int) xvel, (int) yvel))) { setScrollState(SCROLL_STATE_IDLE); } mVelocityTracker.clear(); releaseGlows(); } break; case MotionEvent.ACTION_CANCEL: { cancelTouch(); } break; } return true; } private void cancelTouch() { mVelocityTracker.clear(); releaseGlows(); setScrollState(SCROLL_STATE_IDLE); } private void onPointerUp(MotionEvent e) { final int actionIndex = MotionEventCompat.getActionIndex(e); if (MotionEventCompat.getPointerId(e, actionIndex) == mScrollPointerId) { // Pick a new pointer to pick up the slack. final int newIndex = actionIndex == 0 ? 1 : 0; mScrollPointerId = MotionEventCompat.getPointerId(e, newIndex); mInitialTouchX = mLastTouchX = (int) (MotionEventCompat.getX(e, newIndex) + 0.5f); mInitialTouchY = mLastTouchY = (int) (MotionEventCompat.getY(e, newIndex) + 0.5f); } } @Override protected void onMeasure(int widthSpec, int heightSpec) { if (mAdapterUpdateDuringMeasure) { eatRequestLayout(); mAdapterHelper.preProcess(); mAdapterUpdateDuringMeasure = false; resumeRequestLayout(false); } if (mAdapter != null) { mState.mItemCount = mAdapter.getItemCount(); } mLayout.onMeasure(mRecycler, mState, widthSpec, heightSpec); final int widthSize = getMeasuredWidth(); final int heightSize = getMeasuredHeight(); if (mLeftGlow != null) mLeftGlow.setSize(heightSize, widthSize); if (mTopGlow != null) mTopGlow.setSize(widthSize, heightSize); if (mRightGlow != null) mRightGlow.setSize(heightSize, widthSize); if (mBottomGlow != null) mBottomGlow.setSize(widthSize, heightSize); } /** * Sets the {@link ItemAnimator} that will handle animations involving changes * to the items in this RecyclerView. By default, RecyclerView instantiates and * uses an instance of {@link DefaultItemAnimator}. Whether item animations are * enabled for the RecyclerView depends on the ItemAnimator and whether * the LayoutManager {@link LayoutManager#supportsPredictiveItemAnimations() * supports item animations}. * * @param animator The ItemAnimator being set. If null, no animations will occur * when changes occur to the items in this RecyclerView. */ public void setItemAnimator(ItemAnimator animator) { if (mItemAnimator != null) { mItemAnimator.endAnimations(); mItemAnimator.setListener(null); } mItemAnimator = animator; if (mItemAnimator != null) { mItemAnimator.setListener(mItemAnimatorListener); } } /** * Gets the current ItemAnimator for this RecyclerView. A null return value * indicates that there is no animator and that item changes will happen without * any animations. By default, RecyclerView instantiates and * uses an instance of {@link DefaultItemAnimator}. * * @return ItemAnimator The current ItemAnimator. If null, no animations will occur * when changes occur to the items in this RecyclerView. */ public ItemAnimator getItemAnimator() { return mItemAnimator; } private boolean supportsChangeAnimations() { return mItemAnimator != null && mItemAnimator.getSupportsChangeAnimations(); } /** * Post a runnable to the next frame to run pending item animations. Only the first such * request will be posted, governed by the mPostedAnimatorRunner flag. */ private void postAnimationRunner() { if (!mPostedAnimatorRunner && mIsAttached) { ViewCompat.postOnAnimation(this, mItemAnimatorRunner); mPostedAnimatorRunner = true; } } private boolean predictiveItemAnimationsEnabled() { return (mItemAnimator != null && mLayout.supportsPredictiveItemAnimations()); } /** * Wrapper around layoutChildren() that handles animating changes caused by layout. * Animations work on the assumption that there are five different kinds of items * in play: * PERSISTENT: items are visible before and after layout * REMOVED: items were visible before layout and were removed by the app * ADDED: items did not exist before layout and were added by the app * DISAPPEARING: items exist in the data set before/after, but changed from * visible to non-visible in the process of layout (they were moved off * screen as a side-effect of other changes) * APPEARING: items exist in the data set before/after, but changed from * non-visible to visible in the process of layout (they were moved on * screen as a side-effect of other changes) * The overall approach figures out what items exist before/after layout and * infers one of the five above states for each of the items. Then the animations * are set up accordingly: * PERSISTENT views are moved ({@link ItemAnimator#animateMove(ViewHolder, int, int, int, int)}) * REMOVED views are removed ({@link ItemAnimator#animateRemove(ViewHolder)}) * ADDED views are added ({@link ItemAnimator#animateAdd(ViewHolder)}) * DISAPPEARING views are moved off screen * APPEARING views are moved on screen */ void dispatchLayout() { if (mAdapter == null) { Log.e(TAG, "No adapter attached; skipping layout"); return; } mDisappearingViewsInLayoutPass.clear(); eatRequestLayout(); mRunningLayoutOrScroll = true; // simple animations are a subset of advanced animations (which will cause a // prelayout step) boolean animationTypeSupported = (mItemsAddedOrRemoved && !mItemsChanged) || (mItemsAddedOrRemoved || (mItemsChanged && supportsChangeAnimations())); mState.mRunSimpleAnimations = mFirstLayoutComplete && mItemAnimator != null && (mDataSetHasChangedAfterLayout || animationTypeSupported || mLayout.mRequestedSimpleAnimations) && (!mDataSetHasChangedAfterLayout || mAdapter.hasStableIds()); mState.mRunPredictiveAnimations = mState.mRunSimpleAnimations && animationTypeSupported && !mDataSetHasChangedAfterLayout && predictiveItemAnimationsEnabled(); ArrayMapposition
*/
public ViewHolder findViewHolderForPosition(int position) {
return findViewHolderForPosition(position, false);
}
ViewHolder findViewHolderForPosition(int position, boolean checkNewPosition) {
final int childCount = mChildHelper.getUnfilteredChildCount();
for (int i = 0; i < childCount; i++) {
final ViewHolder holder = getChildViewHolderInt(mChildHelper.getUnfilteredChildAt(i));
if (holder != null && !holder.isRemoved()) {
if (checkNewPosition) {
if (holder.mPosition == position) {
return holder;
}
} else if (holder.getPosition() == position) {
return holder;
}
}
}
// This method should not query cached views. It creates a problem during adapter updates
// when we are dealing with already laid out views. Also, for the public method, it is more
// reasonable to return null if position is not laid out.
return null;
}
/**
* Return the ViewHolder for the item with the given id. The RecyclerView must
* use an Adapter with {@link Adapter#setHasStableIds(boolean) stableIds} to
* return a non-null value.
*
* @param id The id for the requested item
* @return The ViewHolder with the given id
, of null if there
* is no such item.
*/
public ViewHolder findViewHolderForItemId(long id) {
final int childCount = mChildHelper.getUnfilteredChildCount();
for (int i = 0; i < childCount; i++) {
final ViewHolder holder = getChildViewHolderInt(mChildHelper.getUnfilteredChildAt(i));
if (holder != null && holder.getItemId() == id) {
return holder;
}
}
// this method should not query cached views. They are not children so they
// should not be returned in this public method
return null;
}
/**
* Find the topmost view under the given point.
*
* @param x Horizontal position in pixels to search
* @param y Vertical position in pixels to search
* @return The child view under (x, y) or null if no matching child is found
*/
public View findChildViewUnder(float x, float y) {
final int count = mChildHelper.getChildCount();
for (int i = count - 1; i >= 0; i--) {
final View child = mChildHelper.getChildAt(i);
final float translationX = ViewCompat.getTranslationX(child);
final float translationY = ViewCompat.getTranslationY(child);
if (x >= child.getLeft() + translationX &&
x <= child.getRight() + translationX &&
y >= child.getTop() + translationY &&
y <= child.getBottom() + translationY) {
return child;
}
}
return null;
}
/**
* Offset the bounds of all child views by dy
pixels.
* Useful for implementing simple scrolling in {@link LayoutManager LayoutManagers}.
*
* @param dy Vertical pixel offset to apply to the bounds of all child views
*/
public void offsetChildrenVertical(int dy) {
final int childCount = mChildHelper.getChildCount();
for (int i = 0; i < childCount; i++) {
mChildHelper.getChildAt(i).offsetTopAndBottom(dy);
}
}
/**
* Called when an item view is attached to this RecyclerView.
*
* Subclasses of RecyclerView may want to perform extra bookkeeping or modifications * of child views as they become attached. This will be called before a * {@link LayoutManager} measures or lays out the view and is a good time to perform these * changes.
* * @param child Child view that is now attached to this RecyclerView and its associated window */ public void onChildAttachedToWindow(View child) { } /** * Called when an item view is detached from this RecyclerView. * *Subclasses of RecyclerView may want to perform extra bookkeeping or modifications * of child views as they become detached. This will be called as a * {@link LayoutManager} fully detaches the child view from the parent and its window.
* * @param child Child view that is now detached from this RecyclerView and its associated window */ public void onChildDetachedFromWindow(View child) { } /** * Offset the bounds of all child views bydx
pixels.
* Useful for implementing simple scrolling in {@link LayoutManager LayoutManagers}.
*
* @param dx Horizontal pixel offset to apply to the bounds of all child views
*/
public void offsetChildrenHorizontal(int dx) {
final int childCount = mChildHelper.getChildCount();
for (int i = 0; i < childCount; i++) {
mChildHelper.getChildAt(i).offsetLeftAndRight(dx);
}
}
Rect getItemDecorInsetsForChild(View child) {
final LayoutParams lp = (LayoutParams) child.getLayoutParams();
if (!lp.mInsetsDirty) {
return lp.mDecorInsets;
}
final Rect insets = lp.mDecorInsets;
insets.set(0, 0, 0, 0);
final int decorCount = mItemDecorations.size();
for (int i = 0; i < decorCount; i++) {
mTempRect.set(0, 0, 0, 0);
mItemDecorations.get(i).getItemOffsets(mTempRect, child, this, mState);
insets.left += mTempRect.left;
insets.top += mTempRect.top;
insets.right += mTempRect.right;
insets.bottom += mTempRect.bottom;
}
lp.mInsetsDirty = false;
return insets;
}
private class ViewFlinger implements Runnable {
private int mLastFlingX;
private int mLastFlingY;
private ScrollerCompat mScroller;
private Interpolator mInterpolator = sQuinticInterpolator;
// When set to true, postOnAnimation callbacks are delayed until the run method completes
private boolean mEatRunOnAnimationRequest = false;
// Tracks if postAnimationCallback should be re-attached when it is done
private boolean mReSchedulePostAnimationCallback = false;
public ViewFlinger() {
mScroller = ScrollerCompat.create(getContext(), sQuinticInterpolator);
}
@Override
public void run() {
disableRunOnAnimationRequests();
consumePendingUpdateOperations();
// keep a local reference so that if it is changed during onAnimation method, it won't
// cause unexpected behaviors
final ScrollerCompat scroller = mScroller;
final SmoothScroller smoothScroller = mLayout.mSmoothScroller;
if (scroller.computeScrollOffset()) {
final int x = scroller.getCurrX();
final int y = scroller.getCurrY();
final int dx = x - mLastFlingX;
final int dy = y - mLastFlingY;
mLastFlingX = x;
mLastFlingY = y;
int overscrollX = 0, overscrollY = 0;
if (mAdapter != null) {
eatRequestLayout();
mRunningLayoutOrScroll = true;
if (dx != 0) {
final int hresult = mLayout.scrollHorizontallyBy(dx, mRecycler, mState);
overscrollX = dx - hresult;
}
if (dy != 0) {
final int vresult = mLayout.scrollVerticallyBy(dy, mRecycler, mState);
overscrollY = dy - vresult;
}
if (supportsChangeAnimations()) {
// Fix up shadow views used by changing animations
int count = mChildHelper.getChildCount();
for (int i = 0; i < count; i++) {
View view = mChildHelper.getChildAt(i);
ViewHolder holder = getChildViewHolder(view);
if (holder != null && holder.mShadowingHolder != null) {
View shadowingView = holder.mShadowingHolder != null ?
holder.mShadowingHolder.itemView : null;
if (shadowingView != null) {
int left = view.getLeft();
int top = view.getTop();
if (left != shadowingView.getLeft() ||
top != shadowingView.getTop()) {
shadowingView.layout(left, top,
left + shadowingView.getWidth(),
top + shadowingView.getHeight());
}
}
}
}
}
if (smoothScroller != null && !smoothScroller.isPendingInitialRun() &&
smoothScroller.isRunning()) {
smoothScroller.onAnimation(dx - overscrollX, dy - overscrollY);
}
mRunningLayoutOrScroll = false;
resumeRequestLayout(false);
}
if (!mItemDecorations.isEmpty()) {
invalidate();
}
if (ViewCompat.getOverScrollMode(RecyclerView.this) !=
ViewCompat.OVER_SCROLL_NEVER) {
considerReleasingGlowsOnScroll(dx, dy);
}
if (overscrollX != 0 || overscrollY != 0) {
final int vel = (int) scroller.getCurrVelocity();
int velX = 0;
if (overscrollX != x) {
velX = overscrollX < 0 ? -vel : overscrollX > 0 ? vel : 0;
}
int velY = 0;
if (overscrollY != y) {
velY = overscrollY < 0 ? -vel : overscrollY > 0 ? vel : 0;
}
if (ViewCompat.getOverScrollMode(RecyclerView.this) !=
ViewCompat.OVER_SCROLL_NEVER) {
absorbGlows(velX, velY);
}
if ((velX != 0 || overscrollX == x || scroller.getFinalX() == 0) &&
(velY != 0 || overscrollY == y || scroller.getFinalY() == 0)) {
scroller.abortAnimation();
}
}
if (mScrollListener != null && (x != 0 || y != 0)) {
mScrollListener.onScrolled(dx, dy);
}
if (!awakenScrollBars()) {
invalidate();
}
if (scroller.isFinished()) {
setScrollState(SCROLL_STATE_IDLE);
} else {
postOnAnimation();
}
}
// call this after the onAnimation is complete not to have inconsistent callbacks etc.
if (smoothScroller != null && smoothScroller.isPendingInitialRun()) {
smoothScroller.onAnimation(0, 0);
}
enableRunOnAnimationRequests();
}
private void disableRunOnAnimationRequests() {
mReSchedulePostAnimationCallback = false;
mEatRunOnAnimationRequest = true;
}
private void enableRunOnAnimationRequests() {
mEatRunOnAnimationRequest = false;
if (mReSchedulePostAnimationCallback) {
postOnAnimation();
}
}
void postOnAnimation() {
if (mEatRunOnAnimationRequest) {
mReSchedulePostAnimationCallback = true;
} else {
ViewCompat.postOnAnimation(RecyclerView.this, this);
}
}
public void fling(int velocityX, int velocityY) {
setScrollState(SCROLL_STATE_SETTLING);
mLastFlingX = mLastFlingY = 0;
mScroller.fling(0, 0, velocityX, velocityY,
Integer.MIN_VALUE, Integer.MAX_VALUE, Integer.MIN_VALUE, Integer.MAX_VALUE);
postOnAnimation();
}
public void smoothScrollBy(int dx, int dy) {
smoothScrollBy(dx, dy, 0, 0);
}
public void smoothScrollBy(int dx, int dy, int vx, int vy) {
smoothScrollBy(dx, dy, computeScrollDuration(dx, dy, vx, vy));
}
private float distanceInfluenceForSnapDuration(float f) {
f -= 0.5f; // center the values about 0.
f *= 0.3f * Math.PI / 2.0f;
return (float) Math.sin(f);
}
private int computeScrollDuration(int dx, int dy, int vx, int vy) {
final int absDx = Math.abs(dx);
final int absDy = Math.abs(dy);
final boolean horizontal = absDx > absDy;
final int velocity = (int) Math.sqrt(vx * vx + vy * vy);
final int delta = (int) Math.sqrt(dx * dx + dy * dy);
final int containerSize = horizontal ? getWidth() : getHeight();
final int halfContainerSize = containerSize / 2;
final float distanceRatio = Math.min(1.f, 1.f * delta / containerSize);
final float distance = halfContainerSize + halfContainerSize *
distanceInfluenceForSnapDuration(distanceRatio);
final int duration;
if (velocity > 0) {
duration = 4 * Math.round(1000 * Math.abs(distance / velocity));
} else {
float absDelta = (float) (horizontal ? absDx : absDy);
duration = (int) (((absDelta / containerSize) + 1) * 300);
}
return Math.min(duration, MAX_SCROLL_DURATION);
}
public void smoothScrollBy(int dx, int dy, int duration) {
smoothScrollBy(dx, dy, duration, sQuinticInterpolator);
}
public void smoothScrollBy(int dx, int dy, int duration, Interpolator interpolator) {
if (mInterpolator != interpolator) {
mInterpolator = interpolator;
mScroller = ScrollerCompat.create(getContext(), interpolator);
}
setScrollState(SCROLL_STATE_SETTLING);
mLastFlingX = mLastFlingY = 0;
mScroller.startScroll(0, 0, dx, dy, duration);
postOnAnimation();
}
public void stop() {
removeCallbacks(this);
mScroller.abortAnimation();
}
}
private class RecyclerViewDataObserver extends AdapterDataObserver {
@Override
public void onChanged() {
assertNotInLayoutOrScroll(null);
if (mAdapter.hasStableIds()) {
// TODO Determine what actually changed.
// This is more important to implement now since this callback will disable all
// animations because we cannot rely on positions.
mState.mStructureChanged = true;
mDataSetHasChangedAfterLayout = true;
} else {
mState.mStructureChanged = true;
mDataSetHasChangedAfterLayout = true;
}
if (!mAdapterHelper.hasPendingUpdates()) {
requestLayout();
}
}
@Override
public void onItemRangeChanged(int positionStart, int itemCount) {
assertNotInLayoutOrScroll(null);
if (mAdapterHelper.onItemRangeChanged(positionStart, itemCount)) {
triggerUpdateProcessor();
}
}
@Override
public void onItemRangeInserted(int positionStart, int itemCount) {
assertNotInLayoutOrScroll(null);
if (mAdapterHelper.onItemRangeInserted(positionStart, itemCount)) {
triggerUpdateProcessor();
}
}
@Override
public void onItemRangeRemoved(int positionStart, int itemCount) {
assertNotInLayoutOrScroll(null);
if (mAdapterHelper.onItemRangeRemoved(positionStart, itemCount)) {
triggerUpdateProcessor();
}
}
void triggerUpdateProcessor() {
if (mPostUpdatesOnAnimation && mHasFixedSize && mIsAttached) {
ViewCompat.postOnAnimation(RecyclerView.this, mUpdateChildViewsRunnable);
} else {
mAdapterUpdateDuringMeasure = true;
requestLayout();
}
}
}
public static class RecycledViewPool {
private SparseArrayA "scrapped" view is a view that is still attached to its parent RecyclerView but * that has been marked for removal or reuse.
* *Typical use of a Recycler by a {@link LayoutManager} will be to obtain views for * an adapter's data set representing the data at a given position or item ID. * If the view to be reused is considered "dirty" the adapter will be asked to rebind it. * If not, the view can be quickly reused by the LayoutManager with no further work. * Clean views that have not {@link android.view.View#isLayoutRequested() requested layout} * may be repositioned by a LayoutManager without remeasurement.
*/ public final class Recycler { private final ArrayList* Checks whether a given view holder can be used for the provided position. * * @param holder ViewHolder * @return true if ViewHolder matches the provided position, false otherwise */ boolean validateViewHolderForOffsetPosition(ViewHolder holder) { // if it is a removed holder, nothing to verify since we cannot ask adapter anymore // if it is not removed, verify the type and id. if (holder.isRemoved()) { return true; } if (holder.mPosition < 0 || holder.mPosition >= mAdapter.getItemCount()) { throw new IndexOutOfBoundsException("Inconsistency detected. Invalid view holder " + "adapter position" + holder); } final int type = mAdapter.getItemViewType(holder.mPosition); if (type != holder.getItemViewType()) { return false; } if (mAdapter.hasStableIds()) { return holder.getItemId() == mAdapter.getItemId(holder.mPosition); } return true; } /** * Binds the given View to the position. The View can be a View previously retrieved via * {@link #getViewForPosition(int)} or created by * {@link Adapter#onCreateViewHolder(ViewGroup, int)}. *
* Generally, a LayoutManager should acquire its views via {@link #getViewForPosition(int)} * and let the RecyclerView handle caching. This is a helper method for LayoutManager who * wants to handle its own recycling logic. *
* Note that, {@link #getViewForPosition(int)} already binds the View to the position so * you don't need to call this method unless you want to bind this View to another position. * * @param view The view to update. * @param position The position of the item to bind to this View. */ public void bindViewToPosition(View view, int position) { ViewHolder holder = getChildViewHolderInt(view); if (holder == null) { throw new IllegalArgumentException("The view does not have a ViewHolder. You cannot" + " pass arbitrary views to this method, they should be created by the " + "Adapter"); } final int offsetPosition = mAdapterHelper.findPositionOffset(position); if (offsetPosition < 0 || offsetPosition >= mAdapter.getItemCount()) { throw new IndexOutOfBoundsException("Inconsistency detected. Invalid item " + "position " + position + "(offset:" + offsetPosition + ")." + "state:" + mState.getItemCount()); } mAdapter.bindViewHolder(holder, offsetPosition); if (mState.isPreLayout()) { holder.mPreLayoutPosition = position; } ViewGroup.LayoutParams lp = holder.itemView.getLayoutParams(); if (lp == null) { lp = generateDefaultLayoutParams(); holder.itemView.setLayoutParams(lp); } else if (!checkLayoutParams(lp)) { lp = generateLayoutParams(lp); holder.itemView.setLayoutParams(lp); } ((LayoutParams) lp).mInsetsDirty = true; ((LayoutParams) lp).mViewHolder = holder; } /** * Obtain a view initialized for the given position. * * This method should be used by {@link LayoutManager} implementations to obtain * views to represent data from an {@link Adapter}. *
* The Recycler may reuse a scrap or detached view from a shared pool if one is
* available for the correct view type. If the adapter has not indicated that the
* data at the given position has changed, the Recycler will attempt to hand back
* a scrap view that was previously initialized for that data without rebinding.
*
* @param position Position to obtain a view for
* @return A view representing the data at position
from adapter
*/
public View getViewForPosition(int position) {
return getViewForPosition(position, false);
}
View getViewForPosition(int position, boolean dryRun) {
if (position < 0 || position >= mState.getItemCount()) {
throw new IndexOutOfBoundsException("Invalid item position " + position
+ "(" + position + "). Item count:" + mState.getItemCount());
}
ViewHolder holder;
// 1) Find from scrap by position
holder = getScrapViewForPosition(position, INVALID_TYPE, dryRun);
if (holder != null) {
if (!validateViewHolderForOffsetPosition(holder)) {
// recycle this scrap
if (!dryRun) {
// we would like to recycle this but need to make sure it is not used by
// animation logic etc.
holder.addFlags(ViewHolder.FLAG_INVALID);
if (holder.isScrap()) {
removeDetachedView(holder.itemView, false);
holder.unScrap();
} else if (holder.wasReturnedFromScrap()) {
holder.clearReturnedFromScrapFlag();
}
recycleViewHolder(holder);
}
holder = null;
}
}
if (holder == null) {
final int offsetPosition = mAdapterHelper.findPositionOffset(position);
if (offsetPosition < 0 || offsetPosition >= mAdapter.getItemCount()) {
throw new IndexOutOfBoundsException("Inconsistency detected. Invalid item "
+ "position " + position + "(offset:" + offsetPosition + ")."
+ "state:" + mState.getItemCount());
}
final int type = mAdapter.getItemViewType(offsetPosition);
// 2) Find from scrap via stable ids, if exists
if (mAdapter.hasStableIds()) {
holder = getScrapViewForId(mAdapter.getItemId(offsetPosition), type, dryRun);
if (holder != null) {
// update position
holder.mPosition = offsetPosition;
}
}
if (holder == null && mViewCacheExtension != null) {
// We are NOT sending the offsetPosition because LayoutManager does not
// know it.
final View view = mViewCacheExtension
.getViewForPositionAndType(this, position, type);
if (view != null) {
holder = getChildViewHolder(view);
if (holder == null) {
throw new IllegalArgumentException("getViewForPositionAndType returned"
+ " a view which does not have a ViewHolder");
} else if (holder.shouldIgnore()) {
throw new IllegalArgumentException("getViewForPositionAndType returned"
+ " a view that is ignored. You must call stopIgnoring before"
+ " returning this view.");
}
}
}
if (holder == null) { // fallback to recycler
// try recycler.
// Head to the shared pool.
if (DEBUG) {
Log.d(TAG, "getViewForPosition(" + position + ") fetching from shared "
+ "pool");
}
holder = getRecycledViewPool()
.getRecycledView(mAdapter.getItemViewType(offsetPosition));
if (holder != null) {
holder.resetInternal();
}
}
if (holder == null) {
holder = mAdapter.createViewHolder(RecyclerView.this,
mAdapter.getItemViewType(offsetPosition));
if (DEBUG) {
Log.d(TAG, "getViewForPosition created new ViewHolder");
}
}
}
if (!holder.isRemoved() && (!holder.isBound() || holder.needsUpdate() ||
holder.isInvalid())) {
final int offsetPosition = mAdapterHelper.findPositionOffset(position);
mAdapter.bindViewHolder(holder, offsetPosition);
if (mState.isPreLayout()) {
holder.mPreLayoutPosition = position;
}
}
ViewGroup.LayoutParams lp = holder.itemView.getLayoutParams();
if (lp == null) {
lp = generateDefaultLayoutParams();
holder.itemView.setLayoutParams(lp);
} else if (!checkLayoutParams(lp)) {
lp = generateLayoutParams(lp);
holder.itemView.setLayoutParams(lp);
}
((LayoutParams) lp).mViewHolder = holder;
return holder.itemView;
}
/**
* Recycle a detached view. The specified view will be added to a pool of views
* for later rebinding and reuse.
*
*
A view must be fully detached before it may be recycled.
* * @param view Removed view for recycling */ public void recycleView(View view) { recycleViewHolder(getChildViewHolderInt(view)); } void recycleAndClearCachedViews() { final int count = mCachedViews.size(); for (int i = count - 1; i >= 0; i--) { tryToRecycleCachedViewAt(i); } mCachedViews.clear(); } /** * Tries to recyle a cached view and removes the view from the list if and only if it * is recycled. * * @param cachedViewIndex The index of the view in cached views list * @return True if item is recycled */ boolean tryToRecycleCachedViewAt(int cachedViewIndex) { if (DEBUG) { Log.d(TAG, "Recycling cached view at index " + cachedViewIndex); } ViewHolder viewHolder = mCachedViews.get(cachedViewIndex); if (DEBUG) { Log.d(TAG, "CachedViewHolder to be recycled(if recycleable): " + viewHolder); } if (viewHolder.isRecyclable()) { getRecycledViewPool().putRecycledView(viewHolder); dispatchViewRecycled(viewHolder); mCachedViews.remove(cachedViewIndex); return true; } return false; } void recycleViewHolder(ViewHolder holder) { if (holder.isScrap() || holder.itemView.getParent() != null) { throw new IllegalArgumentException( "Scrapped or attached views may not be recycled. isScrap:" + holder.isScrap() + " isAttached:" + (holder.itemView.getParent() != null)); } if (holder.shouldIgnore()) { throw new IllegalArgumentException("Trying to recycle an ignored view holder"); } boolean cached = false; if (!holder.isInvalid() && (mInPreLayout || !holder.isRemoved()) && !holder.isChanged()) { // Retire oldest cached views first if (mCachedViews.size() == mViewCacheMax && !mCachedViews.isEmpty()) { for (int i = 0; i < mCachedViews.size(); i++) { if (tryToRecycleCachedViewAt(i)) { break; } } } if (mCachedViews.size() < mViewCacheMax) { mCachedViews.add(holder); cached = true; } } if (!cached && holder.isRecyclable()) { getRecycledViewPool().putRecycledView(holder); dispatchViewRecycled(holder); } // Remove from pre/post maps that are used to animate items; a recycled holder // should not be animated mState.mPreLayoutHolderMap.remove(holder); mState.mPostLayoutHolderMap.remove(holder); } /** * Used as a fast path for unscrapping and recycling a view during a bulk operation. * The caller must call {@link #clearScrap()} when it's done to update the recycler's * internal bookkeeping. */ void quickRecycleScrapView(View view) { final ViewHolder holder = getChildViewHolderInt(view); holder.mScrapContainer = null; holder.clearReturnedFromScrapFlag(); recycleViewHolder(holder); } /** * Mark an attached view as scrap. * *"Scrap" views are still attached to their parent RecyclerView but are eligible * for rebinding and reuse. Requests for a view for a given position may return a * reused or rebound scrap view instance.
* * @param view View to scrap */ void scrapView(View view) { final ViewHolder holder = getChildViewHolderInt(view); if (holder.isInvalid() && !holder.isRemoved() && !mAdapter.hasStableIds()) { throw new IllegalArgumentException("Called scrap view with an invalid view." + " Invalid views cannot be reused from scrap, they should rebound from" + " recycler pool."); } holder.setScrapContainer(this); if (!holder.isChanged() || !supportsChangeAnimations()) { mAttachedScrap.add(holder); } else { if (mChangedScrap == null) { mChangedScrap = new ArrayListThis view will no longer be eligible for reuse until re-scrapped or * until it is explicitly removed and recycled.
*/ void unscrapView(ViewHolder holder) { if (!holder.isChanged() || !supportsChangeAnimations() || mChangedScrap == null) { mAttachedScrap.remove(holder); } else { mChangedScrap.remove(holder); } holder.mScrapContainer = null; holder.clearReturnedFromScrapFlag(); } int getScrapCount() { return mAttachedScrap.size(); } View getScrapViewAt(int index) { return mAttachedScrap.get(index).itemView; } void clearScrap() { mAttachedScrap.clear(); } /** * Returns a scrap view for the position. If type is not INVALID_TYPE, it also checks if * ViewHolder's type matches the provided type. * * @param position Item position * @param type View type * @param dryRun Does a dry run, finds the ViewHolder but does not remove * @return a ViewHolder that can be re-used for this position. */ ViewHolder getScrapViewForPosition(int position, int type, boolean dryRun) { final int scrapCount = mAttachedScrap.size(); // Try first for an exact, non-invalid match from scrap. for (int i = 0; i < scrapCount; i++) { final ViewHolder holder = mAttachedScrap.get(i); if (!holder.wasReturnedFromScrap() && holder.getPosition() == position && !holder.isInvalid() && (mInPreLayout || !holder.isRemoved())) { if (type != INVALID_TYPE && holder.getItemViewType() != type) { Log.e(TAG, "Scrap view for position " + position + " isn't dirty but has" + " wrong view type! (found " + holder.getItemViewType() + " but expected " + type + ")"); break; } holder.addFlags(ViewHolder.FLAG_RETURNED_FROM_SCRAP); return holder; } } if (!dryRun) { View view = mChildHelper.findHiddenNonRemovedView(position, type); if (view != null) { // ending the animation should cause it to get recycled before we reuse it mItemAnimator.endAnimation(getChildViewHolder(view)); } } // Search in our first-level recycled view cache. final int cacheSize = mCachedViews.size(); for (int i = 0; i < cacheSize; i++) { final ViewHolder holder = mCachedViews.get(i); // invalid view holders may be in cache if adapter has stable ids as they can be // retrieved via getScrapViewForId if (!holder.isInvalid() && holder.getPosition() == position) { if (!dryRun) { mCachedViews.remove(i); } if (DEBUG) { Log.d(TAG, "getScrapViewForPosition(" + position + ", " + type + ") found match in cache: " + holder); } return holder; } } return null; } ViewHolder getScrapViewForId(long id, int type, boolean dryRun) { // Look in our attached views first final int count = mAttachedScrap.size(); for (int i = count - 1; i >= 0; i--) { final ViewHolder holder = mAttachedScrap.get(i); if (holder.getItemId() == id && !holder.wasReturnedFromScrap()) { if (type == holder.getItemViewType()) { holder.addFlags(ViewHolder.FLAG_RETURNED_FROM_SCRAP); if (holder.isRemoved()) { // this might be valid in two cases: // > item is removed but we are in pre-layout pass // >> do nothing. return as is. make sure we don't rebind // > item is removed then added to another position and we are in // post layout. // >> remove removed and invalid flags, add update flag to rebind // because item was invisible to us and we don't know what happened in // between. if (!mState.isPreLayout()) { holder.setFlags(ViewHolder.FLAG_UPDATE, ViewHolder.FLAG_UPDATE | ViewHolder.FLAG_INVALID | ViewHolder.FLAG_REMOVED); } } return holder; } else if (!dryRun) { // Recycle this scrap. Type mismatch. mAttachedScrap.remove(i); removeDetachedView(holder.itemView, false); quickRecycleScrapView(holder.itemView); } } } // Search the first-level cache final int cacheSize = mCachedViews.size(); for (int i = cacheSize - 1; i >= 0; i--) { final ViewHolder holder = mCachedViews.get(i); if (holder.getItemId() == id) { if (type == holder.getItemViewType()) { if (!dryRun) { mCachedViews.remove(i); } return holder; } else if (!dryRun) { tryToRecycleCachedViewAt(i); } } } return null; } void dispatchViewRecycled(ViewHolder holder) { if (mRecyclerListener != null) { mRecyclerListener.onViewRecycled(holder); } if (mAdapter != null) { mAdapter.onViewRecycled(holder); } if (mState != null) { mState.onViewRecycled(holder); } if (DEBUG) Log.d(TAG, "dispatchViewRecycled: " + holder); } void onAdapterChanged(Adapter oldAdapter, Adapter newAdapter) { clear(); getRecycledViewPool().onAdapterChanged(oldAdapter, newAdapter); } void offsetPositionRecordsForInsert(int insertedAt, int count) { final int cachedCount = mCachedViews.size(); for (int i = 0; i < cachedCount; i++) { final ViewHolder holder = mCachedViews.get(i); if (holder != null && holder.getPosition() >= insertedAt) { if (DEBUG) { Log.d(TAG, "offsetPositionRecordsForInsert cached " + i + " holder " + holder + " now at position " + (holder.mPosition + count)); } holder.offsetPosition(count, true); } } } /** * @param removedFrom Remove start index * @param count Remove count * @param applyToPreLayout If true, changes will affect ViewHolder's pre-layout position, if * false, they'll be applied before the second layout pass */ void offsetPositionRecordsForRemove(int removedFrom, int count, boolean applyToPreLayout) { final int removedEnd = removedFrom + count; final int cachedCount = mCachedViews.size(); for (int i = cachedCount - 1; i >= 0; i--) { final ViewHolder holder = mCachedViews.get(i); if (holder != null) { if (holder.getPosition() >= removedEnd) { if (DEBUG) { Log.d(TAG, "offsetPositionRecordsForRemove cached " + i + " holder " + holder + " now at position " + (holder.mPosition - count)); } holder.offsetPosition(-count, applyToPreLayout); } else if (holder.getPosition() >= removedFrom) { // Item for this view was removed. Dump it from the cache. if (!tryToRecycleCachedViewAt(i)) { // if we cannot recycle it, at least invalidate so that we won't return // it by position. holder.addFlags(ViewHolder.FLAG_INVALID); if (DEBUG) { Log.d(TAG, "offsetPositionRecordsForRemove cached " + i + " holder " + holder + " now flagged as invalid because it " + "could not be recycled"); } } else if (DEBUG) { Log.d(TAG, "offsetPositionRecordsForRemove cached " + i + " holder " + holder + " now placed in pool"); } } } } } void setViewCacheExtension(ViewCacheExtension extension) { mViewCacheExtension = extension; } void setRecycledViewPool(RecycledViewPool pool) { if (mRecyclerPool != null) { mRecyclerPool.detach(); } mRecyclerPool = pool; if (pool != null) { mRecyclerPool.attach(getAdapter()); } } RecycledViewPool getRecycledViewPool() { if (mRecyclerPool == null) { mRecyclerPool = new RecycledViewPool(); } return mRecyclerPool; } void viewRangeUpdate(int positionStart, int itemCount) { final int positionEnd = positionStart + itemCount; final int cachedCount = mCachedViews.size(); for (int i = 0; i < cachedCount; i++) { final ViewHolder holder = mCachedViews.get(i); if (holder == null) { continue; } final int pos = holder.getPosition(); if (pos >= positionStart && pos < positionEnd) { holder.addFlags(ViewHolder.FLAG_UPDATE); if (supportsChangeAnimations()) { holder.addFlags(ViewHolder.FLAG_CHANGED); } } } } void markKnownViewsInvalid() { if (mAdapter != null && mAdapter.hasStableIds()) { final int cachedCount = mCachedViews.size(); for (int i = 0; i < cachedCount; i++) { final ViewHolder holder = mCachedViews.get(i); if (holder != null) { holder.addFlags(ViewHolder.FLAG_UPDATE | ViewHolder.FLAG_INVALID); } } } else { // we cannot re-use cached views in this case. Recycle the ones we can and flag // the remaining as invalid so that they can be recycled later on (when their // animations end.) for (int i = mCachedViews.size() - 1; i >= 0; i--) { if (!tryToRecycleCachedViewAt(i)) { final ViewHolder holder = mCachedViews.get(i); holder.addFlags(ViewHolder.FLAG_UPDATE | ViewHolder.FLAG_INVALID); } } } } void clearOldPositions() { final int cachedCount = mCachedViews.size(); for (int i = 0; i < cachedCount; i++) { final ViewHolder holder = mCachedViews.get(i); holder.clearOldPosition(); } } } /** * ViewCacheExtension is a helper class to provide an additional layer of view caching that can * ben controlled by the developer. ** When {@link Recycler#getViewForPosition(int)} is called, Recycler checks attached scrap and * first level cache to find a matching View. If it cannot find a suitable View, Recycler will * call the {@link #getViewForPositionAndType(Recycler, int, int)} before checking * {@link RecycledViewPool}. *
* Note that, Recycler never sends Views to this method to be cached. It is developers * responsibility to decide whether they want to keep their Views in this custom cache or let * the default recycling policy handle it. */ public abstract static class ViewCacheExtension { /** * Returns a View that can be binded to the given Adapter position. *
* This method should not create a new View. Instead, it is expected to return * an already created View that can be re-used for the given type and position. * If the View is marked as ignored, it should first call * {@link LayoutManager#stopIgnoringView(View)} before returning the View. *
* RecyclerView will re-bind the returned View to the position if necessary. * * @param recycler The Recycler that can be used to bind the View * @param position The adapter position * @param type The type of the View, defined by adapter * @return A View that is bound to the given position or NULL if there is no View to re-use * @see LayoutManager#ignoreView(View) */ abstract public View getViewForPositionAndType(Recycler recycler, int position, int type); } /** * Base class for an Adapter * *
Adapters provide a binding from an app-specific data set to views that are displayed * within a {@link RecyclerView}.
*/ public static abstract class Adapterposition
for the purposes
* of view recycling.
*
* The default implementation of this method returns 0, making the assumption of
* a single view type for the adapter. Unlike ListView adapters, types need not
* be contiguous. Consider using id resources to uniquely identify item view types.
*
* @param position position to query
* @return integer value identifying the type of the view needed to represent the item at
* position
. Type codes need not be contiguous.
*/
public int getItemViewType(int position) {
return 0;
}
public void setHasStableIds(boolean hasStableIds) {
if (hasObservers()) {
throw new IllegalStateException("Cannot change whether this adapter has " +
"stable IDs while the adapter has registered observers.");
}
mHasStableIds = hasStableIds;
}
/**
* Return the stable ID for the item at position
. If {@link #hasStableIds()}
* would return false this method should return {@link #NO_ID}. The default implementation
* of this method returns {@link #NO_ID}.
*
* @param position Adapter position to query
* @return the stable ID of the item at position
*/
public long getItemId(int position) {
return NO_ID;
}
public abstract int getItemCount();
/**
* Returns true if this adapter publishes a unique long
value that can
* act as a key for the item at a given position in the data set. If that item is relocated
* in the data set, the ID returned for that item should be the same.
*
* @return true if this adapter's items have stable IDs
*/
public final boolean hasStableIds() {
return mHasStableIds;
}
/**
* Called when a view created by this adapter has been recycled.
*
*
A view is recycled when a {@link LayoutManager} decides that it no longer * needs to be attached to its parent {@link RecyclerView}. This can be because it has * fallen out of visibility or a set of cached views represented by views still * attached to the parent RecyclerView. If an item view has large or expensive data * bound to it such as large bitmaps, this may be a good place to release those * resources.
* * @param holder The ViewHolder for the view being recycled */ public void onViewRecycled(VH holder) { } /** * Called when a view created by this adapter has been attached to a window. * *This can be used as a reasonable signal that the view is about to be seen * by the user. If the adapter previously freed any resources in * {@link #onViewDetachedFromWindow(RecyclerView.ViewHolder) onViewDetachedFromWindow} * those resources should be restored here.
* * @param holder Holder of the view being attached */ public void onViewAttachedToWindow(VH holder) { } /** * Called when a view created by this adapter has been detached from its window. * *Becoming detached from the window is not necessarily a permanent condition; * the consumer of an Adapter's views may choose to cache views offscreen while they * are not visible, attaching an detaching them as appropriate.
* * @param holder Holder of the view being detached */ public void onViewDetachedFromWindow(VH holder) { } /** * Returns true if one or more observers are attached to this adapter. * @return true if this adapter has observers */ public final boolean hasObservers() { return mObservable.hasObservers(); } /** * Register a new observer to listen for data changes. * *The adapter may publish a variety of events describing specific changes. * Not all adapters may support all change types and some may fall back to a generic * {@link android.support.v7.widget.RecyclerView.AdapterDataObserver#onChanged() * "something changed"} event if more specific data is not available.
* *Components registering observers with an adapter are responsible for * {@link #unregisterAdapterDataObserver(android.support.v7.widget.RecyclerView.AdapterDataObserver) * unregistering} those observers when finished.
* * @param observer Observer to register * * @see #unregisterAdapterDataObserver(android.support.v7.widget.RecyclerView.AdapterDataObserver) */ public void registerAdapterDataObserver(AdapterDataObserver observer) { mObservable.registerObserver(observer); } /** * Unregister an observer currently listening for data changes. * *The unregistered observer will no longer receive events about changes * to the adapter.
* * @param observer Observer to unregister * * @see #registerAdapterDataObserver(android.support.v7.widget.RecyclerView.AdapterDataObserver) */ public void unregisterAdapterDataObserver(AdapterDataObserver observer) { mObservable.unregisterObserver(observer); } /** * Notify any registered observers that the data set has changed. * *There are two different classes of data change events, item changes and structural * changes. Item changes are when a single item has its data updated but no positional * changes have occurred. Structural changes are when items are inserted, removed or moved * within the data set.
* *This event does not specify what about the data set has changed, forcing * any observers to assume that all existing items and structure may no longer be valid. * LayoutManagers will be forced to fully rebind and relayout all visible views.
* *RecyclerView
will attempt to synthesize visible structural change events
* for adapters that report that they have {@link #hasStableIds() stable IDs} when
* this method is used. This can help for the purposes of animation and visual
* object persistence but individual item views will still need to be rebound
* and relaid out.
If you are writing an adapter it will always be more efficient to use the more
* specific change events if you can. Rely on notifyDataSetChanged()
* as a last resort.
position
has changed.
*
* This is an item change event, not a structural change event. It indicates that any
* reflection of the data at position
is out of date and should be updated.
* The item at position
retains the same identity.
itemCount
items starting at
* position positionStart
have changed.
*
* This is an item change event, not a structural change event. It indicates that * any reflection of the data in the given position range is out of date and should * be updated. The items in the given range retain the same identity.
* * @param positionStart Position of the first item that has changed * @param itemCount Number of items that have changed * * @see #notifyItemChanged(int) */ public final void notifyItemRangeChanged(int positionStart, int itemCount) { mObservable.notifyItemRangeChanged(positionStart, itemCount); } /** * Notify any registered observers that the item reflected atposition
* has been newly inserted. The item previously at position
is now at
* position position + 1
.
*
* This is a structural change event. Representations of other existing items in the * data set are still considered up to date and will not be rebound, though their * positions may be altered.
* * @param position Position of the newly inserted item in the data set * * @see #notifyItemRangeInserted(int, int) */ public final void notifyItemInserted(int position) { mObservable.notifyItemRangeInserted(position, 1); } /** * Notify any registered observers that the currently reflecteditemCount
* items starting at positionStart
have been newly inserted. The items
* previously located at positionStart
and beyond can now be found starting
* at position positionStart + itemCount
.
*
* This is a structural change event. Representations of other existing items in the * data set are still considered up to date and will not be rebound, though their positions * may be altered.
* * @param positionStart Position of the first item that was inserted * @param itemCount Number of items inserted * * @see #notifyItemInserted(int) */ public final void notifyItemRangeInserted(int positionStart, int itemCount) { mObservable.notifyItemRangeInserted(positionStart, itemCount); } /** * Notify any registered observers that the item previously located atposition
* has been removed from the data set. The items previously located at and after
* position
may now be found at oldPosition - 1
.
*
* This is a structural change event. Representations of other existing items in the * data set are still considered up to date and will not be rebound, though their positions * may be altered.
* * @param position Position of the item that has now been removed * * @see #notifyItemRangeRemoved(int, int) */ public final void notifyItemRemoved(int position) { mObservable.notifyItemRangeRemoved(position, 1); } /** * Notify any registered observers that theitemCount
items previously
* located at positionStart
have been removed from the data set. The items
* previously located at and after positionStart + itemCount
may now be found
* at oldPosition - itemCount
.
*
* This is a structural change event. Representations of other existing items in the data * set are still considered up to date and will not be rebound, though their positions * may be altered.
* * @param positionStart Previous position of the first item that was removed * @param itemCount Number of items removed from the data set */ public final void notifyItemRangeRemoved(int positionStart, int itemCount) { mObservable.notifyItemRangeRemoved(positionStart, itemCount); } } /** * ALayoutManager
is responsible for measuring and positioning item views
* within a RecyclerView
as well as determining the policy for when to recycle
* item views that are no longer visible to the user. By changing the LayoutManager
* a RecyclerView
can be used to implement a standard vertically scrolling list,
* a uniform grid, staggered grids, horizontally scrolling collections and more. Several stock
* layout managers are provided for general use.
*/
public static abstract class LayoutManager {
ChildHelper mChildHelper;
RecyclerView mRecyclerView;
@Nullable
SmoothScroller mSmoothScroller;
private boolean mRequestedSimpleAnimations = false;
void setRecyclerView(RecyclerView recyclerView) {
if (recyclerView == null) {
mRecyclerView = null;
mChildHelper = null;
} else {
mRecyclerView = recyclerView;
mChildHelper = recyclerView.mChildHelper;
}
}
/**
* Calls {@code RecyclerView#requestLayout} on the underlying RecyclerView
*/
public void requestLayout() {
if(mRecyclerView != null) {
mRecyclerView.requestLayout();
}
}
/**
* Checks if RecyclerView is in the middle of a layout or scroll and throws an
* {@link IllegalStateException} if it is not.
*
* @param message The message for the exception. Can be null.
* @see #assertNotInLayoutOrScroll(String)
*/
public void assertInLayoutOrScroll(String message) {
if (mRecyclerView != null) {
mRecyclerView.assertInLayoutOrScroll(message);
}
}
/**
* Checks if RecyclerView is in the middle of a layout or scroll and throws an
* {@link IllegalStateException} if it is.
*
* @param message The message for the exception. Can be null.
* @see #assertInLayoutOrScroll(String)
*/
public void assertNotInLayoutOrScroll(String message) {
if (mRecyclerView != null) {
mRecyclerView.assertNotInLayoutOrScroll(message);
}
}
/**
* Returns whether this LayoutManager supports automatic item animations.
* A LayoutManager wishing to support item animations should obey certain
* rules as outlined in {@link #onLayoutChildren(Recycler, State)}.
* The default return value is false
, so subclasses of LayoutManager
* will not get predictive item animations by default.
*
* Whether item animations are enabled in a RecyclerView is determined both * by the return value from this method and the * {@link RecyclerView#setItemAnimator(ItemAnimator) ItemAnimator} set on the * RecyclerView itself. If the RecyclerView has a non-null ItemAnimator but this * method returns false, then simple item animations will be enabled, in which * views that are moving onto or off of the screen are simply faded in/out. If * the RecyclerView has a non-null ItemAnimator and this method returns true, * then there will be two calls to {@link #onLayoutChildren(Recycler, State)} to * setup up the information needed to more intelligently predict where appearing * and disappearing views should be animated from/to.
* * @return true if predictive item animations should be enabled, false otherwise */ public boolean supportsPredictiveItemAnimations() { return false; } /** * Called when this LayoutManager is both attached to a RecyclerView and that RecyclerView * is attached to a window. * *Subclass implementations should always call through to the superclass implementation. *
* * @param view The RecyclerView this LayoutManager is bound to */ public void onAttachedToWindow(RecyclerView view) { } /** * @deprecated * override {@link #onDetachedFromWindow(RecyclerView, Recycler)} */ @Deprecated public void onDetachedFromWindow(RecyclerView view) { } /** * Called when this LayoutManager is detached from its parent RecyclerView or when * its parent RecyclerView is detached from its window. * *Subclass implementations should always call through to the superclass implementation. *
* * @param view The RecyclerView this LayoutManager is bound to * @param recycler The recycler to use if you prefer to recycle your children instead of * keeping them around. */ public void onDetachedFromWindow(RecyclerView view, Recycler recycler) { onDetachedFromWindow(view); } /** * Lay out all relevant child views from the given adapter. * * The LayoutManager is in charge of the behavior of item animations. By default, * RecyclerView has a non-null {@link #getItemAnimator() ItemAnimator}, and simple * item animations are enabled. This means that add/remove operations on the * adapter will result in animations to add new or appearing items, removed or * disappearing items, and moved items. If a LayoutManager returns false from * {@link #supportsPredictiveItemAnimations()}, which is the default, and runs a * normal layout operation during {@link #onLayoutChildren(Recycler, State)}, the * RecyclerView will have enough information to run those animations in a simple * way. For example, the default ItemAnimator, {@link DefaultItemAnimator}, will * simple fade views in and out, whether they are actuall added/removed or whether * they are moved on or off the screen due to other add/remove operations. * *A LayoutManager wanting a better item animation experience, where items can be * animated onto and off of the screen according to where the items exist when they * are not on screen, then the LayoutManager should return true from * {@link #supportsPredictiveItemAnimations()} and add additional logic to * {@link #onLayoutChildren(Recycler, State)}. Supporting predictive animations * means that {@link #onLayoutChildren(Recycler, State)} will be called twice; * once as a "pre" layout step to determine where items would have been prior to * a real layout, and again to do the "real" layout. In the pre-layout phase, * items will remember their pre-layout positions to allow them to be laid out * appropriately. Also, {@link LayoutParams#isItemRemoved() removed} items will * be returned from the scrap to help determine correct placement of other items. * These removed items should not be added to the child list, but should be used * to help calculate correct positioning of other views, including views that * were not previously onscreen (referred to as APPEARING views), but whose * pre-layout offscreen position can be determined given the extra * information about the pre-layout removed views.
* *The second layout pass is the real layout in which only non-removed views * will be used. The only additional requirement during this pass is, if * {@link #supportsPredictiveItemAnimations()} returns true, to note which * views exist in the child list prior to layout and which are not there after * layout (referred to as DISAPPEARING views), and to position/layout those views * appropriately, without regard to the actual bounds of the RecyclerView. This allows * the animation system to know the location to which to animate these disappearing * views.
* *The default LayoutManager implementations for RecyclerView handle all of these * requirements for animations already. Clients of RecyclerView can either use one * of these layout managers directly or look at their implementations of * onLayoutChildren() to see how they account for the APPEARING and * DISAPPEARING views.
* * @param recycler Recycler to use for fetching potentially cached views for a * position * @param state Transient state of RecyclerView */ public void onLayoutChildren(Recycler recycler, State state) { Log.e(TAG, "You must override onLayoutChildren(Recycler recycler, State state) "); } /** * Create a defaultLayoutParams
object for a child of the RecyclerView.
*
* LayoutManagers will often want to use a custom LayoutParams
type
* to store extra information specific to the layout. Client code should subclass
* {@link RecyclerView.LayoutParams} for this purpose.
Important: if you use your own custom LayoutParams
type
* you must also override
* {@link #checkLayoutParams(LayoutParams)},
* {@link #generateLayoutParams(android.view.ViewGroup.LayoutParams)} and
* {@link #generateLayoutParams(android.content.Context, android.util.AttributeSet)}.
This should check to make sure that the object is of the correct type
* and all values are within acceptable ranges. The default implementation
* returns true
for non-null params.
Important: if you use your own custom LayoutParams
type
* you must also override
* {@link #checkLayoutParams(LayoutParams)},
* {@link #generateLayoutParams(android.view.ViewGroup.LayoutParams)} and
* {@link #generateLayoutParams(android.content.Context, android.util.AttributeSet)}.
Important: if you use your own custom LayoutParams
type
* you must also override
* {@link #checkLayoutParams(LayoutParams)},
* {@link #generateLayoutParams(android.view.ViewGroup.LayoutParams)} and
* {@link #generateLayoutParams(android.content.Context, android.util.AttributeSet)}.
Math.abs(result)
may be less than dx if a boundary was reached.
*/
public int scrollHorizontallyBy(int dx, Recycler recycler, State state) {
return 0;
}
/**
* Scroll vertically by dy pixels in screen coordinates and return the distance traveled.
* The default implementation does nothing and returns 0.
*
* @param dy distance to scroll in pixels. Y increases as scroll position
* approaches the bottom.
* @param recycler Recycler to use for fetching potentially cached views for a
* position
* @param state Transient state of RecyclerView
* @return The actual distance scrolled. The return value will be negative if dy was
* negative and scrolling proceeeded in that direction.
* Math.abs(result)
may be less than dy if a boundary was reached.
*/
public int scrollVerticallyBy(int dy, Recycler recycler, State state) {
return 0;
}
/**
* Query if horizontal scrolling is currently supported. The default implementation
* returns false.
*
* @return True if this LayoutManager can scroll the current contents horizontally
*/
public boolean canScrollHorizontally() {
return false;
}
/**
* Query if vertical scrolling is currently supported. The default implementation
* returns false.
*
* @return True if this LayoutManager can scroll the current contents vertically
*/
public boolean canScrollVertically() {
return false;
}
/**
* Scroll to the specified adapter position.
*
* Actual position of the item on the screen depends on the LayoutManager implementation.
* @param position Scroll to this adapter position.
*/
public void scrollToPosition(int position) {
if (DEBUG) {
Log.e(TAG, "You MUST implement scrollToPosition. It will soon become abstract");
}
}
/**
* Smooth scroll to the specified adapter position.
*To support smooth scrolling, override this method, create your {@link SmoothScroller} * instance and call {@link #startSmoothScroll(SmoothScroller)}. *
* @param recyclerView The RecyclerView to which this layout manager is attached * @param state Current State of RecyclerView * @param position Scroll to this adapter position. */ public void smoothScrollToPosition(RecyclerView recyclerView, State state, int position) { Log.e(TAG, "You must override smoothScrollToPosition to support smooth scrolling"); } /** *Starts a smooth scroll using the provided SmoothScroller.
*Calling this method will cancel any previous smooth scroll request.
* @param smoothScroller Unstance which defines how smooth scroll should be animated */ public void startSmoothScroll(SmoothScroller smoothScroller) { if (mSmoothScroller != null && smoothScroller != mSmoothScroller && mSmoothScroller.isRunning()) { mSmoothScroller.stop(); } mSmoothScroller = smoothScroller; mSmoothScroller.start(mRecyclerView, this); } /** * @return true if RecycylerView is currently in the state of smooth scrolling. */ public boolean isSmoothScrolling() { return mSmoothScroller != null && mSmoothScroller.isRunning(); } /** * Returns the resolved layout direction for this RecyclerView. * * @return {@link android.support.v4.view.ViewCompat#LAYOUT_DIRECTION_RTL} if the layout * direction is RTL or returns * {@link android.support.v4.view.ViewCompat#LAYOUT_DIRECTION_LTR} if the layout direction * is not RTL. */ public int getLayoutDirection() { return ViewCompat.getLayoutDirection(mRecyclerView); } /** * Ends all animations on the view created by the {@link ItemAnimator}. * * @param view The View for which the animations should be ended. * @see RecyclerView.ItemAnimator#endAnimations() */ public void endAnimation(View view) { if (mRecyclerView.mItemAnimator != null) { mRecyclerView.mItemAnimator.endAnimation(getChildViewHolderInt(view)); } } /** * To be called only during {@link #onLayoutChildren(Recycler, State)} to add a view * to the layout that is known to be going away, either because it has been * {@link Adapter#notifyItemRemoved(int) removed} or because it is actually not in the * visible portion of the container but is being laid out in order to inform RecyclerView * in how to animate the item out of view. ** Views added via this method are going to be invisible to LayoutManager after the * dispatchLayout pass is complete. They cannot be retrieved via {@link #getChildAt(int)} * or won't be included in {@link #getChildCount()} method. * * @param child View to add and then remove with animation. */ public void addDisappearingView(View child) { addDisappearingView(child, -1); } /** * To be called only during {@link #onLayoutChildren(Recycler, State)} to add a view * to the layout that is known to be going away, either because it has been * {@link Adapter#notifyItemRemoved(int) removed} or because it is actually not in the * visible portion of the container but is being laid out in order to inform RecyclerView * in how to animate the item out of view. *
* Views added via this method are going to be invisible to LayoutManager after the * dispatchLayout pass is complete. They cannot be retrieved via {@link #getChildAt(int)} * or won't be included in {@link #getChildCount()} method. * * @param child View to add and then remove with animation. * @param index Index of the view. */ public void addDisappearingView(View child, int index) { addViewInt(child, index, true); } /** * Add a view to the currently attached RecyclerView if needed. LayoutManagers should * use this method to add views obtained from a {@link Recycler} using * {@link Recycler#getViewForPosition(int)}. * * @param child View to add */ public void addView(View child) { addView(child, -1); } /** * Add a view to the currently attached RecyclerView if needed. LayoutManagers should * use this method to add views obtained from a {@link Recycler} using * {@link Recycler#getViewForPosition(int)}. * * @param child View to add * @param index Index to add child at */ public void addView(View child, int index) { addViewInt(child, index, false); } private void addViewInt(View child, int index, boolean disappearing) { final ViewHolder holder = getChildViewHolderInt(child); if (disappearing || holder.isRemoved()) { // these views will be hidden at the end of the layout pass. mRecyclerView.mDisappearingViewsInLayoutPass.add(child); } else { // This may look like unnecessary but may happen if layout manager supports // predictive layouts and adapter removed then re-added the same item. // In this case, added version will be visible in the post layout (because add is // deferred) but RV will still bind it to the same View. // So if a View re-appears in post layout pass, remove it from disappearing list. mRecyclerView.mDisappearingViewsInLayoutPass.remove(child); } if (holder.wasReturnedFromScrap() || holder.isScrap()) { if (holder.isScrap()) { holder.unScrap(); } else { holder.clearReturnedFromScrapFlag(); } mChildHelper.attachViewToParent(child, index, child.getLayoutParams(), false); if (DISPATCH_TEMP_DETACH) { ViewCompat.dispatchFinishTemporaryDetach(child); } } else if (child.getParent() == mRecyclerView) { // it was not a scrap but a valid child // ensure in correct position int currentIndex = mChildHelper.indexOfChild(child); if (index == -1) { index = mChildHelper.getChildCount(); } if (currentIndex == -1) { throw new IllegalStateException("Added View has RecyclerView as parent but" + " view is not a real child. Unfiltered index:" + mRecyclerView.indexOfChild(child)); } if (currentIndex != index) { mRecyclerView.mLayout.moveView(currentIndex, index); } } else { mChildHelper.addView(child, index, false); final LayoutParams lp = (LayoutParams) child.getLayoutParams(); lp.mInsetsDirty = true; final Adapter adapter = mRecyclerView.getAdapter(); if (adapter != null) { adapter.onViewAttachedToWindow(getChildViewHolderInt(child)); } mRecyclerView.onChildAttachedToWindow(child); if (mSmoothScroller != null && mSmoothScroller.isRunning()) { mSmoothScroller.onChildAttachedToWindow(child); } } } /** * Remove a view from the currently attached RecyclerView if needed. LayoutManagers should * use this method to completely remove a child view that is no longer needed. * LayoutManagers should strongly consider recycling removed views using * {@link Recycler#recycleView(android.view.View)}. * * @param child View to remove */ public void removeView(View child) { final Adapter adapter = mRecyclerView.getAdapter(); if (adapter != null) { adapter.onViewDetachedFromWindow(getChildViewHolderInt(child)); } mRecyclerView.onChildDetachedFromWindow(child); mChildHelper.removeView(child); } /** * Remove a view from the currently attached RecyclerView if needed. LayoutManagers should * use this method to completely remove a child view that is no longer needed. * LayoutManagers should strongly consider recycling removed views using * {@link Recycler#recycleView(android.view.View)}. * * @param index Index of the child view to remove */ public void removeViewAt(int index) { final View child = getChildAt(index); if (child != null) { final Adapter adapter = mRecyclerView.getAdapter(); if (adapter != null) { adapter.onViewDetachedFromWindow(getChildViewHolderInt(child)); } mRecyclerView.onChildDetachedFromWindow(child); mChildHelper.removeViewAt(index); } } /** * Remove all views from the currently attached RecyclerView. This will not recycle * any of the affected views; the LayoutManager is responsible for doing so if desired. */ public void removeAllViews() { final Adapter adapter = mRecyclerView.getAdapter(); // Only remove non-animating views final int childCount = getChildCount(); for (int i = 0; i < childCount; i++) { final View child = getChildAt(i); if (adapter != null) { adapter.onViewDetachedFromWindow(getChildViewHolderInt(child)); } mRecyclerView.onChildDetachedFromWindow(child); } for (int i = childCount - 1; i >= 0; i--) { mChildHelper.removeViewAt(i); } } /** * Returns the adapter position of the item represented by the given View. * * @param view The view to query * @return The adapter position of the item which is rendered by this View. */ public int getPosition(View view) { return ((RecyclerView.LayoutParams) view.getLayoutParams()).getViewPosition(); } /** * Returns the View type defined by the adapter. * * @param view The view to query * @return The type of the view assigned by the adapter. */ public int getItemViewType(View view) { return getChildViewHolderInt(view).getItemViewType(); } /** *
Finds the view which represents the given adapter position.
*This method traverses each child since it has no information about child order. * Override this method to improve performance if your LayoutManager keeps data about * child views.
* * @param position Position of the item in adapter * @return The child view that represents the given position or null if the position is not * visible */ public View findViewByPosition(int position) { final int childCount = getChildCount(); for (int i = 0; i < childCount; i++) { View child = getChildAt(i); ViewHolder vh = getChildViewHolderInt(child); if (vh == null) { continue; } if (vh.getPosition() == position && (mRecyclerView.mState.isPreLayout() || !vh.isRemoved())) { return child; } } return null; } /** * Temporarily detach a child view. * *LayoutManagers may want to perform a lightweight detach operation to rearrange * views currently attached to the RecyclerView. Generally LayoutManager implementations * will want to use {@link #detachAndScrapView(android.view.View, RecyclerView.Recycler)} * so that the detached view may be rebound and reused.
* *If a LayoutManager uses this method to detach a view, it must * {@link #attachView(android.view.View, int, RecyclerView.LayoutParams) reattach} * or {@link #removeDetachedView(android.view.View) fully remove} the detached view * before the LayoutManager entry point method called by RecyclerView returns.
* * @param child Child to detach */ public void detachView(View child) { if (DISPATCH_TEMP_DETACH) { ViewCompat.dispatchStartTemporaryDetach(child); } mRecyclerView.detachViewFromParent(child); } /** * Temporarily detach a child view. * *LayoutManagers may want to perform a lightweight detach operation to rearrange * views currently attached to the RecyclerView. Generally LayoutManager implementations * will want to use {@link #detachAndScrapView(android.view.View, RecyclerView.Recycler)} * so that the detached view may be rebound and reused.
* *If a LayoutManager uses this method to detach a view, it must * {@link #attachView(android.view.View, int, RecyclerView.LayoutParams) reattach} * or {@link #removeDetachedView(android.view.View) fully remove} the detached view * before the LayoutManager entry point method called by RecyclerView returns.
* * @param index Index of the child to detach */ public void detachViewAt(int index) { if (DISPATCH_TEMP_DETACH) { ViewCompat.dispatchStartTemporaryDetach(getChildAt(index)); } mChildHelper.detachViewFromParent(index); } /** * Reattach a previously {@link #detachView(android.view.View) detached} view. * This method should not be used to reattach views that were previously * {@link #detachAndScrapView(android.view.View, RecyclerView.Recycler)} scrapped}. * * @param child Child to reattach * @param index Intended child index for child * @param lp LayoutParams for child */ public void attachView(View child, int index, LayoutParams lp) { ViewHolder vh = getChildViewHolderInt(child); if (vh.isRemoved()) { mRecyclerView.mDisappearingViewsInLayoutPass.add(child); } else { mRecyclerView.mDisappearingViewsInLayoutPass.remove(child); } mChildHelper.attachViewToParent(child, index, lp, vh.isRemoved()); if (DISPATCH_TEMP_DETACH) { ViewCompat.dispatchFinishTemporaryDetach(child); } } /** * Reattach a previously {@link #detachView(android.view.View) detached} view. * This method should not be used to reattach views that were previously * {@link #detachAndScrapView(android.view.View, RecyclerView.Recycler)} scrapped}. * * @param child Child to reattach * @param index Intended child index for child */ public void attachView(View child, int index) { attachView(child, index, (LayoutParams) child.getLayoutParams()); } /** * Reattach a previously {@link #detachView(android.view.View) detached} view. * This method should not be used to reattach views that were previously * {@link #detachAndScrapView(android.view.View, RecyclerView.Recycler)} scrapped}. * * @param child Child to reattach */ public void attachView(View child) { attachView(child, -1); } /** * Finish removing a view that was previously temporarily * {@link #detachView(android.view.View) detached}. * * @param child Detached child to remove */ public void removeDetachedView(View child) { mRecyclerView.removeDetachedView(child, false); } /** * Moves a View from one position to another. * * @param fromIndex The View's initial index * @param toIndex The View's target index */ public void moveView(int fromIndex, int toIndex) { View view = getChildAt(fromIndex); if (view == null) { throw new IllegalArgumentException("Cannot move a child from non-existing index:" + fromIndex); } detachViewAt(fromIndex); attachView(view, toIndex); } /** * Detach a child view and add it to a {@link Recycler Recycler's} scrap heap. * *Scrapping a view allows it to be rebound and reused to show updated or * different data.
* * @param child Child to detach and scrap * @param recycler Recycler to deposit the new scrap view into */ public void detachAndScrapView(View child, Recycler recycler) { int index = mChildHelper.indexOfChild(child); scrapOrRecycleView(recycler, index, child); } /** * Detach a child view and add it to a {@link Recycler Recycler's} scrap heap. * *Scrapping a view allows it to be rebound and reused to show updated or * different data.
* * @param index Index of child to detach and scrap * @param recycler Recycler to deposit the new scrap view into */ public void detachAndScrapViewAt(int index, Recycler recycler) { final View child = getChildAt(index); scrapOrRecycleView(recycler, index, child); } /** * Remove a child view and recycle it using the given Recycler. * * @param child Child to remove and recycle * @param recycler Recycler to use to recycle child */ public void removeAndRecycleView(View child, Recycler recycler) { removeView(child); recycler.recycleView(child); } /** * Remove a child view and recycle it using the given Recycler. * * @param index Index of child to remove and recycle * @param recycler Recycler to use to recycle child */ public void removeAndRecycleViewAt(int index, Recycler recycler) { final View view = getChildAt(index); removeViewAt(index); recycler.recycleView(view); } /** * Return the current number of child views attached to the parent RecyclerView. * This does not include child views that were temporarily detached and/or scrapped. * * @return Number of attached children */ public int getChildCount() { return mChildHelper != null ? mChildHelper.getChildCount() : 0; } /** * Return the child view at the given index * @param index Index of child to return * @return Child view at index */ public View getChildAt(int index) { return mChildHelper != null ? mChildHelper.getChildAt(index) : null; } /** * Return the width of the parent RecyclerView * * @return Width in pixels */ public int getWidth() { return mRecyclerView != null ? mRecyclerView.getWidth() : 0; } /** * Return the height of the parent RecyclerView * * @return Height in pixels */ public int getHeight() { return mRecyclerView != null ? mRecyclerView.getHeight() : 0; } /** * Return the left padding of the parent RecyclerView * * @return Padding in pixels */ public int getPaddingLeft() { return mRecyclerView != null ? mRecyclerView.getPaddingLeft() : 0; } /** * Return the top padding of the parent RecyclerView * * @return Padding in pixels */ public int getPaddingTop() { return mRecyclerView != null ? mRecyclerView.getPaddingTop() : 0; } /** * Return the right padding of the parent RecyclerView * * @return Padding in pixels */ public int getPaddingRight() { return mRecyclerView != null ? mRecyclerView.getPaddingRight() : 0; } /** * Return the bottom padding of the parent RecyclerView * * @return Padding in pixels */ public int getPaddingBottom() { return mRecyclerView != null ? mRecyclerView.getPaddingBottom() : 0; } /** * Return the start padding of the parent RecyclerView * * @return Padding in pixels */ public int getPaddingStart() { return mRecyclerView != null ? ViewCompat.getPaddingStart(mRecyclerView) : 0; } /** * Return the end padding of the parent RecyclerView * * @return Padding in pixels */ public int getPaddingEnd() { return mRecyclerView != null ? ViewCompat.getPaddingEnd(mRecyclerView) : 0; } /** * Returns true if the RecyclerView this LayoutManager is bound to has focus. * * @return True if the RecyclerView has focus, false otherwise. * @see View#isFocused() */ public boolean isFocused() { return mRecyclerView != null && mRecyclerView.isFocused(); } /** * Returns true if the RecyclerView this LayoutManager is bound to has or contains focus. * * @return true if the RecyclerView has or contains focus * @see View#hasFocus() */ public boolean hasFocus() { return mRecyclerView != null && mRecyclerView.hasFocus(); } /** * Return the number of items in the adapter bound to the parent RecyclerView * * @return Items in the bound adapter */ public int getItemCount() { final Adapter a = mRecyclerView != null ? mRecyclerView.getAdapter() : null; return a != null ? a.getItemCount() : 0; } /** * Offset all child views attached to the parent RecyclerView by dx pixels along * the horizontal axis. * * @param dx Pixels to offset by */ public void offsetChildrenHorizontal(int dx) { if (mRecyclerView != null) { mRecyclerView.offsetChildrenHorizontal(dx); } } /** * Offset all child views attached to the parent RecyclerView by dy pixels along * the vertical axis. * * @param dy Pixels to offset by */ public void offsetChildrenVertical(int dy) { if (mRecyclerView != null) { mRecyclerView.offsetChildrenVertical(dy); } } /** * Flags a view so that it will not be scrapped or recycled. ** Note that View is still a child of the ViewGroup. If LayoutManager calls methods like * {@link LayoutManager#offsetChildrenHorizontal(int)}, this View will be offset as well. * * @param view View to ignore. */ public void ignoreView(View view) { if (view.getParent() != mRecyclerView || mRecyclerView.indexOfChild(view) == -1) { // checking this because calling this method on a recycled or detached view may // cause loss of state. throw new IllegalArgumentException("View should be fully attached to be ignored"); } final ViewHolder vh = getChildViewHolderInt(view); vh.addFlags(ViewHolder.FLAG_IGNORE); mRecyclerView.mState.onViewIgnored(vh); } /** * View can be scrapped and recycled again. *
* Note that calling this method removes all information in the view holder. * * @param view View to ignore. */ public void stopIgnoringView(View view) { final ViewHolder vh = getChildViewHolderInt(view); vh.stopIgnoring(); vh.resetInternal(); vh.addFlags(ViewHolder.FLAG_INVALID); } /** * Temporarily detach and scrap all currently attached child views. Views will be scrapped * into the given Recycler. The Recycler may prefer to reuse scrap views before * other views that were previously recycled. * * @param recycler Recycler to scrap views into */ public void detachAndScrapAttachedViews(Recycler recycler) { final int childCount = getChildCount(); for (int i = childCount - 1; i >= 0; i--) { final View v = getChildAt(i); scrapOrRecycleView(recycler, i, v); } } private void scrapOrRecycleView(Recycler recycler, int index, View view) { final ViewHolder viewHolder = getChildViewHolderInt(view); if (viewHolder.shouldIgnore()) { if (DEBUG) { Log.d(TAG, "ignoring view " + viewHolder); } return; } if (viewHolder.isInvalid() && !viewHolder.isRemoved() && !mRecyclerView.mAdapter.hasStableIds()) { removeViewAt(index); recycler.recycleView(view); } else { detachViewAt(index); recycler.scrapView(view); } } /** * Recycles the scrapped views. *
* When a view is detached and removed, it does not trigger a ViewGroup invalidate. This is * the expected behavior if scrapped views are used for animations. Otherwise, we need to * call remove and invalidate RecyclerView to ensure UI update. * * @param recycler Recycler * @param remove Whether scrapped views should be removed from ViewGroup or not. This * method will invalidate RecyclerView if it removes any scrapped child. */ void removeAndRecycleScrapInt(Recycler recycler, boolean remove) { final int scrapCount = recycler.getScrapCount(); for (int i = 0; i < scrapCount; i++) { final View scrap = recycler.getScrapViewAt(i); if (getChildViewHolderInt(scrap).shouldIgnore()) { continue; } if (remove) { mRecyclerView.removeDetachedView(scrap, false); } recycler.quickRecycleScrapView(scrap); } recycler.clearScrap(); if (remove && scrapCount > 0) { mRecyclerView.invalidate(); } } /** * Measure a child view using standard measurement policy, taking the padding * of the parent RecyclerView and any added item decorations into account. * *
If the RecyclerView can be scrolled in either dimension the caller may * pass 0 as the widthUsed or heightUsed parameters as they will be irrelevant.
* * @param child Child view to measure * @param widthUsed Width in pixels currently consumed by other views, if relevant * @param heightUsed Height in pixels currently consumed by other views, if relevant */ public void measureChild(View child, int widthUsed, int heightUsed) { final LayoutParams lp = (LayoutParams) child.getLayoutParams(); final Rect insets = mRecyclerView.getItemDecorInsetsForChild(child); widthUsed += insets.left + insets.right; heightUsed += insets.top + insets.bottom; final int widthSpec = getChildMeasureSpec(getWidth(), getPaddingLeft() + getPaddingRight() + widthUsed, lp.width, canScrollHorizontally()); final int heightSpec = getChildMeasureSpec(getHeight(), getPaddingTop() + getPaddingBottom() + heightUsed, lp.height, canScrollVertically()); child.measure(widthSpec, heightSpec); } /** * Measure a child view using standard measurement policy, taking the padding * of the parent RecyclerView, any added item decorations and the child margins * into account. * *If the RecyclerView can be scrolled in either dimension the caller may * pass 0 as the widthUsed or heightUsed parameters as they will be irrelevant.
* * @param child Child view to measure * @param widthUsed Width in pixels currently consumed by other views, if relevant * @param heightUsed Height in pixels currently consumed by other views, if relevant */ public void measureChildWithMargins(View child, int widthUsed, int heightUsed) { final LayoutParams lp = (LayoutParams) child.getLayoutParams(); final Rect insets = mRecyclerView.getItemDecorInsetsForChild(child); widthUsed += insets.left + insets.right; heightUsed += insets.top + insets.bottom; final int widthSpec = getChildMeasureSpec(getWidth(), getPaddingLeft() + getPaddingRight() + lp.leftMargin + lp.rightMargin + widthUsed, lp.width, canScrollHorizontally()); final int heightSpec = getChildMeasureSpec(getHeight(), getPaddingTop() + getPaddingBottom() + lp.topMargin + lp.bottomMargin + heightUsed, lp.height, canScrollVertically()); child.measure(widthSpec, heightSpec); } /** * Calculate a MeasureSpec value for measuring a child view in one dimension. * * @param parentSize Size of the parent view where the child will be placed * @param padding Total space currently consumed by other elements of parent * @param childDimension Desired size of the child view, or MATCH_PARENT/WRAP_CONTENT. * Generally obtained from the child view's LayoutParams * @param canScroll true if the parent RecyclerView can scroll in this dimension * * @return a MeasureSpec value for the child view */ public static int getChildMeasureSpec(int parentSize, int padding, int childDimension, boolean canScroll) { int size = Math.max(0, parentSize - padding); int resultSize = 0; int resultMode = 0; if (canScroll) { if (childDimension >= 0) { resultSize = childDimension; resultMode = MeasureSpec.EXACTLY; } else { // MATCH_PARENT can't be applied since we can scroll in this dimension, wrap // instead using UNSPECIFIED. resultSize = 0; resultMode = MeasureSpec.UNSPECIFIED; } } else { if (childDimension >= 0) { resultSize = childDimension; resultMode = MeasureSpec.EXACTLY; } else if (childDimension == LayoutParams.FILL_PARENT) { resultSize = size; resultMode = MeasureSpec.EXACTLY; } else if (childDimension == LayoutParams.WRAP_CONTENT) { resultSize = size; resultMode = MeasureSpec.AT_MOST; } } return MeasureSpec.makeMeasureSpec(resultSize, resultMode); } /** * Returns the measured width of the given child, plus the additional size of * any insets applied by {@link ItemDecoration ItemDecorations}. * * @param child Child view to query * @return child's measured width plusItemDecoration
insets
*
* @see View#getMeasuredWidth()
*/
public int getDecoratedMeasuredWidth(View child) {
final Rect insets = ((LayoutParams) child.getLayoutParams()).mDecorInsets;
return child.getMeasuredWidth() + insets.left + insets.right;
}
/**
* Returns the measured height of the given child, plus the additional size of
* any insets applied by {@link ItemDecoration ItemDecorations}.
*
* @param child Child view to query
* @return child's measured height plus ItemDecoration
insets
*
* @see View#getMeasuredHeight()
*/
public int getDecoratedMeasuredHeight(View child) {
final Rect insets = ((LayoutParams) child.getLayoutParams()).mDecorInsets;
return child.getMeasuredHeight() + insets.top + insets.bottom;
}
/**
* Lay out the given child view within the RecyclerView using coordinates that
* include any current {@link ItemDecoration ItemDecorations}.
*
* LayoutManagers should prefer working in sizes and coordinates that include * item decoration insets whenever possible. This allows the LayoutManager to effectively * ignore decoration insets within measurement and layout code. See the following * methods:
*This is the LayoutManager's opportunity to populate views in the given direction * to fulfill the request if it can. The LayoutManager should attach and return * the view to be focused. The default implementation returns null.
* * @param focused The currently focused view * @param direction One of {@link View#FOCUS_UP}, {@link View#FOCUS_DOWN}, * {@link View#FOCUS_LEFT}, {@link View#FOCUS_RIGHT}, * {@link View#FOCUS_BACKWARD}, {@link View#FOCUS_FORWARD} * or 0 for not applicable * @param recycler The recycler to use for obtaining views for currently offscreen items * @param state Transient state of RecyclerView * @return The chosen view to be focused */ public View onFocusSearchFailed(View focused, int direction, Recycler recycler, State state) { return null; } /** * This method gives a LayoutManager an opportunity to intercept the initial focus search * before the default behavior of {@link FocusFinder} is used. If this method returns * null FocusFinder will attempt to find a focusable child view. If it fails * then {@link #onFocusSearchFailed(View, int, RecyclerView.Recycler, RecyclerView.State)} * will be called to give the LayoutManager an opportunity to add new views for items * that did not have attached views representing them. The LayoutManager should not add * or remove views from this method. * * @param focused The currently focused view * @param direction One of {@link View#FOCUS_UP}, {@link View#FOCUS_DOWN}, * {@link View#FOCUS_LEFT}, {@link View#FOCUS_RIGHT}, * {@link View#FOCUS_BACKWARD}, {@link View#FOCUS_FORWARD} * @return A descendant view to focus or null to fall back to default behavior. * The default implementation returns null. */ public View onInterceptFocusSearch(View focused, int direction) { return null; } /** * Called when a child of the RecyclerView wants a particular rectangle to be positioned * onto the screen. See {@link ViewParent#requestChildRectangleOnScreen(android.view.View, * android.graphics.Rect, boolean)} for more details. * *The base implementation will attempt to perform a standard programmatic scroll * to bring the given rect into view, within the padded area of the RecyclerView.
* * @param child The direct child making the request. * @param rect The rectangle in the child's coordinates the child * wishes to be on the screen. * @param immediate True to forbid animated or delayed scrolling, * false otherwise * @return Whether the group scrolled to handle the operation */ public boolean requestChildRectangleOnScreen(RecyclerView parent, View child, Rect rect, boolean immediate) { final int parentLeft = getPaddingLeft(); final int parentTop = getPaddingTop(); final int parentRight = getWidth() - getPaddingRight(); final int parentBottom = getHeight() - getPaddingBottom(); final int childLeft = child.getLeft() + rect.left; final int childTop = child.getTop() + rect.top; final int childRight = childLeft + rect.right; final int childBottom = childTop + rect.bottom; final int offScreenLeft = Math.min(0, childLeft - parentLeft); final int offScreenTop = Math.min(0, childTop - parentTop); final int offScreenRight = Math.max(0, childRight - parentRight); final int offScreenBottom = Math.max(0, childBottom - parentBottom); // Favor the "start" layout direction over the end when bringing one side or the other // of a large rect into view. final int dx; if (ViewCompat.getLayoutDirection(parent) == ViewCompat.LAYOUT_DIRECTION_RTL) { dx = offScreenRight != 0 ? offScreenRight : offScreenLeft; } else { dx = offScreenLeft != 0 ? offScreenLeft : offScreenRight; } // Favor bringing the top into view over the bottom final int dy = offScreenTop != 0 ? offScreenTop : offScreenBottom; if (dx != 0 || dy != 0) { if (immediate) { parent.scrollBy(dx, dy); } else { parent.smoothScrollBy(dx, dy); } return true; } return false; } /** * @deprecated Use {@link #onRequestChildFocus(RecyclerView, State, View, View)} */ @Deprecated public boolean onRequestChildFocus(RecyclerView parent, View child, View focused) { return false; } /** * Called when a descendant view of the RecyclerView requests focus. * *A LayoutManager wishing to keep focused views aligned in a specific * portion of the view may implement that behavior in an override of this method.
* *If the LayoutManager executes different behavior that should override the default * behavior of scrolling the focused child on screen instead of running alongside it, * this method should return true.
* * @param parent The RecyclerView hosting this LayoutManager * @param state Current state of RecyclerView * @param child Direct child of the RecyclerView containing the newly focused view * @param focused The newly focused view. This may be the same view as child * @return true if the default scroll behavior should be suppressed */ public boolean onRequestChildFocus(RecyclerView parent, State state, View child, View focused) { return onRequestChildFocus(parent, child, focused); } /** * Called if the RecyclerView this LayoutManager is bound to has a different adapter set. * The LayoutManager may use this opportunity to clear caches and configure state such * that it can relayout appropriately with the new data and potentially new view types. * *The default implementation removes all currently attached views.
* * @param oldAdapter The previous adapter instance. Will be null if there was previously no * adapter. * @param newAdapter The new adapter instance. Might be null if * {@link #setAdapter(RecyclerView.Adapter)} is called with {@code null}. */ public void onAdapterChanged(Adapter oldAdapter, Adapter newAdapter) { } /** * Called to populate focusable views within the RecyclerView. * *The LayoutManager implementation should return true
if the default
* behavior of {@link ViewGroup#addFocusables(java.util.ArrayList, int)} should be
* suppressed.
The default implementation returns false
to trigger RecyclerView
* to fall back to the default ViewGroup behavior.
Override this method if you want to support scroll bars.
* *Read {@link RecyclerView#computeHorizontalScrollExtent()} for details.
* *Default implementation returns 0.
* * @param state Current state of RecyclerView * @return The horizontal extent of the scrollbar's thumb * @see RecyclerView#computeHorizontalScrollExtent() */ public int computeHorizontalScrollExtent(State state) { return 0; } /** *Override this method if you want to support scroll bars.
* *Read {@link RecyclerView#computeHorizontalScrollOffset()} for details.
* *Default implementation returns 0.
* * @param state Current State of RecyclerView where you can find total item count * @return The horizontal offset of the scrollbar's thumb * @see RecyclerView#computeHorizontalScrollOffset() */ public int computeHorizontalScrollOffset(State state) { return 0; } /** *Override this method if you want to support scroll bars.
* *Read {@link RecyclerView#computeHorizontalScrollRange()} for details.
* *Default implementation returns 0.
* * @param state Current State of RecyclerView where you can find total item count * @return The total horizontal range represented by the vertical scrollbar * @see RecyclerView#computeHorizontalScrollRange() */ public int computeHorizontalScrollRange(State state) { return 0; } /** *Override this method if you want to support scroll bars.
* *Read {@link RecyclerView#computeVerticalScrollExtent()} for details.
* *Default implementation returns 0.
* * @param state Current state of RecyclerView * @return The vertical extent of the scrollbar's thumb * @see RecyclerView#computeVerticalScrollExtent() */ public int computeVerticalScrollExtent(State state) { return 0; } /** *Override this method if you want to support scroll bars.
* *Read {@link RecyclerView#computeVerticalScrollOffset()} for details.
* *Default implementation returns 0.
* * @param state Current State of RecyclerView where you can find total item count * @return The vertical offset of the scrollbar's thumb * @see RecyclerView#computeVerticalScrollOffset() */ public int computeVerticalScrollOffset(State state) { return 0; } /** *Override this method if you want to support scroll bars.
* *Read {@link RecyclerView#computeVerticalScrollRange()} for details.
* *Default implementation returns 0.
* * @param state Current State of RecyclerView where you can find total item count * @return The total vertical range represented by the vertical scrollbar * @see RecyclerView#computeVerticalScrollRange() */ public int computeVerticalScrollRange(State state) { return 0; } /** * Measure the attached RecyclerView. Implementations must call * {@link #setMeasuredDimension(int, int)} before returning. * *The default implementation will handle EXACTLY measurements and respect * the minimum width and height properties of the host RecyclerView if measured * as UNSPECIFIED. AT_MOST measurements will be treated as EXACTLY and the RecyclerView * will consume all available space.
* * @param recycler Recycler * @param state Transient state of RecyclerView * @param widthSpec Width {@link android.view.View.MeasureSpec} * @param heightSpec Height {@link android.view.View.MeasureSpec} */ public void onMeasure(Recycler recycler, State state, int widthSpec, int heightSpec) { final int widthMode = MeasureSpec.getMode(widthSpec); final int heightMode = MeasureSpec.getMode(heightSpec); final int widthSize = MeasureSpec.getSize(widthSpec); final int heightSize = MeasureSpec.getSize(heightSpec); int width = 0; int height = 0; switch (widthMode) { case MeasureSpec.EXACTLY: case MeasureSpec.AT_MOST: width = widthSize; break; case MeasureSpec.UNSPECIFIED: default: width = getMinimumWidth(); break; } switch (heightMode) { case MeasureSpec.EXACTLY: case MeasureSpec.AT_MOST: height = heightSize; break; case MeasureSpec.UNSPECIFIED: default: height = getMinimumHeight(); break; } setMeasuredDimension(width, height); } /** * {@link View#setMeasuredDimension(int, int) Set the measured dimensions} of the * host RecyclerView. * * @param widthSize Measured width * @param heightSize Measured height */ public void setMeasuredDimension(int widthSize, int heightSize) { mRecyclerView.setMeasuredDimension(widthSize, heightSize); } /** * @return The host RecyclerView's {@link View#getMinimumWidth()} */ public int getMinimumWidth() { return ViewCompat.getMinimumWidth(mRecyclerView); } /** * @return The host RecyclerView's {@link View#getMinimumHeight()} */ public int getMinimumHeight() { return ViewCompat.getMinimumHeight(mRecyclerView); } /** *Called when the LayoutManager should save its state. This is a good time to save your * scroll position, configuration and anything else that may be required to restore the same * layout state if the LayoutManager is recreated.
*RecyclerView does NOT verify if the LayoutManager has changed between state save and * restore. This will let you share information between your LayoutManagers but it is also * your responsibility to make sure they use the same parcelable class.
* * @return Necessary information for LayoutManager to be able to restore its state */ public Parcelable onSaveInstanceState() { return null; } public void onRestoreInstanceState(Parcelable state) { } void stopSmoothScroller() { if (mSmoothScroller != null) { mSmoothScroller.stop(); } } private void onSmoothScrollerStopped(SmoothScroller smoothScroller) { if (mSmoothScroller == smoothScroller) { mSmoothScroller = null; } } /** * RecyclerView calls this method to notify LayoutManager that scroll state has changed. * * @param state The new scroll state for RecyclerView */ public void onScrollStateChanged(int state) { } /** * Removes all views and recycles them using the given recycler. ** If you want to clean cached views as well, you should call {@link Recycler#clear()} too. * * @param recycler Recycler to use to recycle children * @see #removeAndRecycleView(View, Recycler) * @see #removeAndRecycleViewAt(int, Recycler) */ public void removeAndRecycleAllViews(Recycler recycler) { for (int i = getChildCount() - 1; i >= 0; i--) { removeAndRecycleViewAt(i, recycler); } } /** * A LayoutManager can call this method to force RecyclerView to run simple animations in * the next layout pass, even if there is not any trigger to do so. (e.g. adapter data * change). *
* Note that, calling this method will not guarantee that RecyclerView will run animations * at all. For example, if there is not any {@link ItemAnimator} set, RecyclerView will * not run any animations but will still clear this flag after the layout is complete. * */ public void requestSimpleAnimationsInNextLayout() { mRequestedSimpleAnimations = true; } } /** * An ItemDecoration allows the application to add a special drawing and layout offset * to specific item views from the adapter's data set. This can be useful for drawing dividers * between items, highlights, visual grouping boundaries and more. * *
All ItemDecorations are drawn in the order they were added, before the item * views (in {@link ItemDecoration#onDraw(Canvas, RecyclerView, RecyclerView.State) onDraw()} * and after the items (in {@link ItemDecoration#onDrawOver(Canvas, RecyclerView, * RecyclerView.State)}.
*/ public static abstract class ItemDecoration { /** * Draw any appropriate decorations into the Canvas supplied to the RecyclerView. * Any content drawn by this method will be drawn before the item views are drawn, * and will thus appear underneath the views. * * @param c Canvas to draw into * @param parent RecyclerView this ItemDecoration is drawing into * @param state The current state of RecyclerView */ public void onDraw(Canvas c, RecyclerView parent, State state) { onDraw(c, parent); } /** * @deprecated * Override {@link #onDraw(Canvas, RecyclerView, RecyclerView.State)} */ @Deprecated public void onDraw(Canvas c, RecyclerView parent) { } /** * Draw any appropriate decorations into the Canvas supplied to the RecyclerView. * Any content drawn by this method will be drawn after the item views are drawn * and will thus appear over the views. * * @param c Canvas to draw into * @param parent RecyclerView this ItemDecoration is drawing into * @param state The current state of RecyclerView. */ public void onDrawOver(Canvas c, RecyclerView parent, State state) { onDrawOver(c, parent); } /** * @deprecated * Override {@link #onDrawOver(Canvas, RecyclerView, RecyclerView.State)} */ @Deprecated public void onDrawOver(Canvas c, RecyclerView parent) { } /** * @deprecated * Use {@link #getItemOffsets(Rect, View, RecyclerView, State)} */ @Deprecated public void getItemOffsets(Rect outRect, int itemPosition, RecyclerView parent) { outRect.set(0, 0, 0, 0); } /** * Retrieve any offsets for the given item. Each field ofoutRect
specifies
* the number of pixels that the item view should be inset by, similar to padding or margin.
* The default implementation sets the bounds of outRect to 0 and returns.
*
* If this ItemDecoration does not affect the positioning of item views it should set
* all four fields of outRect
(left, top, right, bottom) to zero
* before returning.
This can be useful for applications that wish to implement various forms of gestural * manipulation of item views within the RecyclerView. OnItemTouchListeners may intercept * a touch interaction already in progress even if the RecyclerView is already handling that * gesture stream itself for the purposes of scrolling.
*/ public interface OnItemTouchListener { /** * Silently observe and/or take over touch events sent to the RecyclerView * before they are handled by either the RecyclerView itself or its child views. * *The onInterceptTouchEvent methods of each attached OnItemTouchListener will be run * in the order in which each listener was added, before any other touch processing * by the RecyclerView itself or child views occurs.
* * @param e MotionEvent describing the touch event. All coordinates are in * the RecyclerView's coordinate system. * @return true if this OnItemTouchListener wishes to begin intercepting touch events, false * to continue with the current behavior and continue observing future events in * the gesture. */ public boolean onInterceptTouchEvent(RecyclerView rv, MotionEvent e); /** * Process a touch event as part of a gesture that was claimed by returning true from * a previous call to {@link #onInterceptTouchEvent}. * * @param e MotionEvent describing the touch event. All coordinates are in * the RecyclerView's coordinate system. */ public void onTouchEvent(RecyclerView rv, MotionEvent e); } /** * An OnScrollListener can be set on a RecyclerView to receive messages * when a scrolling event has occurred on that RecyclerView. * * @see RecyclerView#setOnScrollListener(OnScrollListener) */ public interface OnScrollListener { public void onScrollStateChanged(int newState); public void onScrolled(int dx, int dy); } /** * A RecyclerListener can be set on a RecyclerView to receive messages whenever * a view is recycled. * * @see RecyclerView#setRecyclerListener(RecyclerListener) */ public interface RecyclerListener { /** * This method is called whenever the view in the ViewHolder is recycled. * * @param holder The ViewHolder containing the view that was recycled */ public void onViewRecycled(ViewHolder holder); } /** * A ViewHolder describes an item view and metadata about its place within the RecyclerView. * *{@link Adapter} implementations should subclass ViewHolder and add fields for caching * potentially expensive {@link View#findViewById(int)} results.
* *While {@link LayoutParams} belong to the {@link LayoutManager},
* {@link ViewHolder ViewHolders} belong to the adapter. Adapters should feel free to use
* their own custom ViewHolder implementations to store data that makes binding view contents
* easier. Implementations should assume that individual item views will hold strong references
* to ViewHolder
objects and that RecyclerView
instances may hold
* strong references to extra off-screen item views for caching purposes
* If a ViewHolder was laid out in the previous onLayout call, old position will keep its
* adapter index in the previous layout.
*
* @return The previous adapter index of the Item represented by this ViewHolder or
* {@link #NO_POSITION} if old position does not exists or cleared (pre-layout is
* complete).
*/
public final int getOldPosition() {
return mOldPosition;
}
/**
* Returns The itemId represented by this ViewHolder.
*
* @return The the item's id if adapter has stable ids, {@link RecyclerView#NO_ID}
* otherwise
*/
public final long getItemId() {
return mItemId;
}
/**
* @return The view type of this ViewHolder.
*/
public final int getItemViewType() {
return mItemViewType;
}
boolean isScrap() {
return mScrapContainer != null;
}
void unScrap() {
mScrapContainer.unscrapView(this);
}
boolean wasReturnedFromScrap() {
return (mFlags & FLAG_RETURNED_FROM_SCRAP) != 0;
}
void clearReturnedFromScrapFlag() {
mFlags = mFlags & ~FLAG_RETURNED_FROM_SCRAP;
}
void stopIgnoring() {
mFlags = mFlags & ~FLAG_IGNORE;
}
void setScrapContainer(Recycler recycler) {
mScrapContainer = recycler;
}
boolean isInvalid() {
return (mFlags & FLAG_INVALID) != 0;
}
boolean needsUpdate() {
return (mFlags & FLAG_UPDATE) != 0;
}
boolean isChanged() {
return (mFlags & FLAG_CHANGED) != 0;
}
boolean isBound() {
return (mFlags & FLAG_BOUND) != 0;
}
boolean isRemoved() {
return (mFlags & FLAG_REMOVED) != 0;
}
void setFlags(int flags, int mask) {
mFlags = (mFlags & ~mask) | (flags & mask);
}
void addFlags(int flags) {
mFlags |= flags;
}
void resetInternal() {
mFlags = 0;
mPosition = NO_POSITION;
mOldPosition = NO_POSITION;
mItemId = NO_ID;
mPreLayoutPosition = NO_POSITION;
mIsRecyclableCount = 0;
}
@Override
public String toString() {
final StringBuilder sb = new StringBuilder("ViewHolder{" +
Integer.toHexString(hashCode()) + " position=" + mPosition + " id=" + mItemId +
", oldPos=" + mOldPosition + ", pLpos:" + mPreLayoutPosition);
if (isScrap()) sb.append(" scrap");
if (isInvalid()) sb.append(" invalid");
if (!isBound()) sb.append(" unbound");
if (needsUpdate()) sb.append(" update");
if (isRemoved()) sb.append(" removed");
if (shouldIgnore()) sb.append(" ignored");
if (!isRecyclable()) sb.append(" not recyclable");
if (itemView.getParent() == null) sb.append(" no parent");
sb.append("}");
return sb.toString();
}
/**
* Informs the recycler whether this item can be recycled. Views which are not
* recyclable will not be reused for other items until setIsRecyclable() is
* later set to true. Calls to setIsRecyclable() should always be paired (one
* call to setIsRecyclabe(false) should always be matched with a later call to
* setIsRecyclable(true)). Pairs of calls may be nested, as the state is internally
* reference-counted.
*
* @param recyclable Whether this item is available to be recycled. Default value
* is true.
*/
public final void setIsRecyclable(boolean recyclable) {
mIsRecyclableCount = recyclable ? mIsRecyclableCount - 1 : mIsRecyclableCount + 1;
if (DEBUG) {
Log.d(TAG, "setIsRecyclable for item id:" + mItemId + "val:" + recyclable + ","
+ "cnt:" + mIsRecyclableCount);
}
if (mIsRecyclableCount < 0) {
mIsRecyclableCount = 0;
Log.e(VIEW_LOG_TAG, "isRecyclable decremented below 0: " +
"unmatched pair of setIsRecyable() calls");
} else if (!recyclable && mIsRecyclableCount == 1) {
mFlags |= FLAG_NOT_RECYCLABLE;
} else if (recyclable && mIsRecyclableCount == 0) {
mFlags &= ~FLAG_NOT_RECYCLABLE;
}
}
/**
* @see {@link #setIsRecyclable(boolean)}
*
* @return true if this item is available to be recycled, false otherwise.
*/
public final boolean isRecyclable() {
return (mFlags & FLAG_NOT_RECYCLABLE) == 0 &&
!ViewCompat.hasTransientState(itemView);
}
}
/**
* {@link android.view.ViewGroup.MarginLayoutParams LayoutParams} subclass for children of
* {@link RecyclerView}. Custom {@link LayoutManager layout managers} are encouraged
* to create their own subclass of this LayoutParams
class
* to store any additional required per-child view metadata about the layout.
*/
public static class LayoutParams extends android.view.ViewGroup.MarginLayoutParams {
ViewHolder mViewHolder;
final Rect mDecorInsets = new Rect();
boolean mInsetsDirty = true;
public LayoutParams(Context c, AttributeSet attrs) {
super(c, attrs);
}
public LayoutParams(int width, int height) {
super(width, height);
}
public LayoutParams(MarginLayoutParams source) {
super(source);
}
public LayoutParams(ViewGroup.LayoutParams source) {
super(source);
}
public LayoutParams(LayoutParams source) {
super((ViewGroup.LayoutParams) source);
}
/**
* Returns true if the view this LayoutParams is attached to needs to have its content
* updated from the corresponding adapter.
*
* @return true if the view should have its content updated
*/
public boolean viewNeedsUpdate() {
return mViewHolder.needsUpdate();
}
/**
* Returns true if the view this LayoutParams is attached to is now representing
* potentially invalid data. A LayoutManager should scrap/recycle it.
*
* @return true if the view is invalid
*/
public boolean isViewInvalid() {
return mViewHolder.isInvalid();
}
/**
* Returns true if the adapter data item corresponding to the view this LayoutParams
* is attached to has been removed from the data set. A LayoutManager may choose to
* treat it differently in order to animate its outgoing or disappearing state.
*
* @return true if the item the view corresponds to was removed from the data set
*/
public boolean isItemRemoved() {
return mViewHolder.isRemoved();
}
/**
* Returns the position that the view this LayoutParams is attached to corresponds to.
*
* @return the adapter position this view was bound from
*/
public int getViewPosition() {
return mViewHolder.getPosition();
}
}
/**
* Observer base class for watching changes to an {@link Adapter}.
* See {@link Adapter#registerAdapterDataObserver(AdapterDataObserver)}.
*/
public static abstract class AdapterDataObserver {
public void onChanged() {
// Do nothing
}
public void onItemRangeChanged(int positionStart, int itemCount) {
// do nothing
}
public void onItemRangeInserted(int positionStart, int itemCount) {
// do nothing
}
public void onItemRangeRemoved(int positionStart, int itemCount) {
// do nothing
}
}
/**
*
Base class for smooth scrolling. Handles basic tracking of the target view position and * provides methods to trigger a programmatic scroll.
* * @see LinearSmoothScroller */ public static abstract class SmoothScroller { private int mTargetPosition = RecyclerView.NO_POSITION; private RecyclerView mRecyclerView; private LayoutManager mLayoutManager; private boolean mPendingInitialRun; private boolean mRunning; private View mTargetView; private final Action mRecyclingAction; public SmoothScroller() { mRecyclingAction = new Action(0, 0); } /** * Starts a smooth scroll for the given target position. *In each animation step, {@link RecyclerView} will check * for the target view and call either * {@link #onTargetFound(android.view.View, RecyclerView.State, SmoothScroller.Action)} or * {@link #onSeekTargetStep(int, int, RecyclerView.State, SmoothScroller.Action)} until * SmoothScroller is stopped.
* *Note that if RecyclerView finds the target view, it will automatically stop the * SmoothScroller. This does not mean that scroll will stop, it only means it will * stop calling SmoothScroller in each animation step.
*/ void start(RecyclerView recyclerView, LayoutManager layoutManager) { mRecyclerView = recyclerView; mLayoutManager = layoutManager; if (mTargetPosition == RecyclerView.NO_POSITION) { throw new IllegalArgumentException("Invalid target position"); } mRecyclerView.mState.mTargetPosition = mTargetPosition; mRunning = true; mPendingInitialRun = true; mTargetView = findViewByPosition(getTargetPosition()); onStart(); mRecyclerView.mViewFlinger.postOnAnimation(); } public void setTargetPosition(int targetPosition) { mTargetPosition = targetPosition; } /** * @return The LayoutManager to which this SmoothScroller is attached */ public LayoutManager getLayoutManager() { return mLayoutManager; } /** * Stops running the SmoothScroller in each animation callback. Note that this does not * cancel any existing {@link Action} updated by * {@link #onTargetFound(android.view.View, RecyclerView.State, SmoothScroller.Action)} or * {@link #onSeekTargetStep(int, int, RecyclerView.State, SmoothScroller.Action)}. */ final protected void stop() { if (!mRunning) { return; } onStop(); mRecyclerView.mState.mTargetPosition = RecyclerView.NO_POSITION; mTargetView = null; mTargetPosition = RecyclerView.NO_POSITION; mPendingInitialRun = false; mRunning = false; // trigger a cleanup mLayoutManager.onSmoothScrollerStopped(this); // clear references to avoid any potential leak by a custom smooth scroller mLayoutManager = null; mRecyclerView = null; } /** * Returns true if SmoothScroller has beens started but has not received the first * animation * callback yet. * * @return True if this SmoothScroller is waiting to start */ public boolean isPendingInitialRun() { return mPendingInitialRun; } /** * @return True if SmoothScroller is currently active */ public boolean isRunning() { return mRunning; } /** * Returns the adapter position of the target item * * @return Adapter position of the target item or * {@link RecyclerView#NO_POSITION} if no target view is set. */ public int getTargetPosition() { return mTargetPosition; } private void onAnimation(int dx, int dy) { if (!mRunning || mTargetPosition == RecyclerView.NO_POSITION) { stop(); } mPendingInitialRun = false; if (mTargetView != null) { // verify target position if (getChildPosition(mTargetView) == mTargetPosition) { onTargetFound(mTargetView, mRecyclerView.mState, mRecyclingAction); mRecyclingAction.runIfNecessary(mRecyclerView); stop(); } else { Log.e(TAG, "Passed over target position while smooth scrolling."); mTargetView = null; } } if (mRunning) { onSeekTargetStep(dx, dy, mRecyclerView.mState, mRecyclingAction); mRecyclingAction.runIfNecessary(mRecyclerView); } } /** * @see RecyclerView#getChildPosition(android.view.View) */ public int getChildPosition(View view) { return mRecyclerView.getChildPosition(view); } /** * @see RecyclerView.LayoutManager#getChildCount() */ public int getChildCount() { return mRecyclerView.mLayout.getChildCount(); } /** * @see RecyclerView.LayoutManager#findViewByPosition(int) */ public View findViewByPosition(int position) { return mRecyclerView.mLayout.findViewByPosition(position); } /** * @see RecyclerView#scrollToPosition(int) */ public void instantScrollToPosition(int position) { mRecyclerView.scrollToPosition(position); } protected void onChildAttachedToWindow(View child) { if (getChildPosition(child) == getTargetPosition()) { mTargetView = child; if (DEBUG) { Log.d(TAG, "smooth scroll target view has been attached"); } } } /** * Normalizes the vector. * @param scrollVector The vector that points to the target scroll position */ protected void normalize(PointF scrollVector) { final double magnitute = Math.sqrt(scrollVector.x * scrollVector.x + scrollVector.y * scrollVector.y); scrollVector.x /= magnitute; scrollVector.y /= magnitute; } /** * Called when smooth scroll is started. This might be a good time to do setup. */ abstract protected void onStart(); /** * Called when smooth scroller is stopped. This is a good place to cleanup your state etc. * @see #stop() */ abstract protected void onStop(); /** *RecyclerView will call this method each time it scrolls until it can find the target * position in the layout.
*SmoothScroller should check dx, dy and if scroll should be changed, update the * provided {@link Action} to define the next scroll.
* * @param dx Last scroll amount horizontally * @param dy Last scroll amount verticaully * @param state Transient state of RecyclerView * @param action If you want to trigger a new smooth scroll and cancel the previous one, * update this object. */ abstract protected void onSeekTargetStep(int dx, int dy, State state, Action action); /** * Called when the target position is laid out. This is the last callback SmoothScroller * will receive and it should update the provided {@link Action} to define the scroll * details towards the target view. * @param targetView The view element which render the target position. * @param state Transient state of RecyclerView * @param action Action instance that you should update to define final scroll action * towards the targetView * @return An {@link Action} to finalize the smooth scrolling */ abstract protected void onTargetFound(View targetView, State state, Action action); /** * Holds information about a smooth scroll request by a {@link SmoothScroller}. */ public static class Action { public static final int UNDEFINED_DURATION = Integer.MIN_VALUE; private int mDx; private int mDy; private int mDuration; private Interpolator mInterpolator; private boolean changed = false; // we track this variable to inform custom implementer if they are updating the action // in every animation callback private int consecutiveUpdates = 0; /** * @param dx Pixels to scroll horizontally * @param dy Pixels to scroll vertically */ public Action(int dx, int dy) { this(dx, dy, UNDEFINED_DURATION, null); } /** * @param dx Pixels to scroll horizontally * @param dy Pixels to scroll vertically * @param duration Duration of the animation in milliseconds */ public Action(int dx, int dy, int duration) { this(dx, dy, duration, null); } /** * @param dx Pixels to scroll horizontally * @param dy Pixels to scroll vertically * @param duration Duration of the animation in milliseconds * @param interpolator Interpolator to be used when calculating scroll position in each * animation step */ public Action(int dx, int dy, int duration, Interpolator interpolator) { mDx = dx; mDy = dy; mDuration = duration; mInterpolator = interpolator; } private void runIfNecessary(RecyclerView recyclerView) { if (changed) { validate(); if (mInterpolator == null) { if (mDuration == UNDEFINED_DURATION) { recyclerView.mViewFlinger.smoothScrollBy(mDx, mDy); } else { recyclerView.mViewFlinger.smoothScrollBy(mDx, mDy, mDuration); } } else { recyclerView.mViewFlinger.smoothScrollBy(mDx, mDy, mDuration, mInterpolator); } consecutiveUpdates ++; if (consecutiveUpdates > 10) { // A new action is being set in every animation step. This looks like a bad // implementation. Inform developer. Log.e(TAG, "Smooth Scroll action is being updated too frequently. Make sure" + " you are not changing it unless necessary"); } changed = false; } else { consecutiveUpdates = 0; } } private void validate() { if (mInterpolator != null && mDuration < 1) { throw new IllegalStateException("If you provide an interpolator, you must" + " set a positive duration"); } else if (mDuration < 1) { throw new IllegalStateException("Scroll duration must be a positive number"); } } public int getDx() { return mDx; } public void setDx(int dx) { changed = true; mDx = dx; } public int getDy() { return mDy; } public void setDy(int dy) { changed = true; mDy = dy; } public int getDuration() { return mDuration; } public void setDuration(int duration) { changed = true; mDuration = duration; } public Interpolator getInterpolator() { return mInterpolator; } /** * Sets the interpolator to calculate scroll steps * @param interpolator The interpolator to use. If you specify an interpolator, you must * also set the duration. * @see #setDuration(int) */ public void setInterpolator(Interpolator interpolator) { changed = true; mInterpolator = interpolator; } /** * Updates the action with given parameters. * @param dx Pixels to scroll horizontally * @param dy Pixels to scroll vertically * @param duration Duration of the animation in milliseconds * @param interpolator Interpolator to be used when calculating scroll position in each * animation step */ public void update(int dx, int dy, int duration, Interpolator interpolator) { mDx = dx; mDy = dy; mDuration = duration; mInterpolator = interpolator; changed = true; } } } static class AdapterDataObservable extends ObservableContains useful information about the current RecyclerView state like target scroll * position or view focus. State object can also keep arbitrary data, identified by resource * ids.
*Often times, RecyclerView components will need to pass information between each other. * To provide a well defined data bus between components, RecyclerView passes the same State * object to component callbacks and these components can use it to exchange data.
*If you implement custom components, you can use State's put/get/remove methods to pass * data between your components without needing to manage their lifecycles.
*/ public static class State { private int mTargetPosition = RecyclerView.NO_POSITION; private ArrayMap