/*
* Copyright 2018 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 androidx.viewpager2.adapter;
import android.os.Bundle;
import android.os.Parcelable;
import android.view.View;
import android.view.ViewGroup;
import android.widget.FrameLayout;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.collection.LongSparseArray;
import androidx.core.view.ViewCompat;
import androidx.fragment.app.Fragment;
import androidx.fragment.app.FragmentManager;
import androidx.fragment.app.FragmentStatePagerAdapter;
import androidx.fragment.app.FragmentTransaction;
import androidx.recyclerview.widget.RecyclerView;
/**
* Similar in behavior to {@link FragmentStatePagerAdapter}
* <p>
* Lifecycle within {@link RecyclerView}:
* <ul>
* <li>{@link RecyclerView.ViewHolder} initially an empty {@link FrameLayout}, serves as a
* re-usable container for a {@link Fragment} in later stages.
* <li>{@link RecyclerView.Adapter#onBindViewHolder} we ask for a {@link Fragment} for the
* position. If we already have the fragment, or have previously saved its state, we use those.
* <li>{@link RecyclerView.Adapter#onAttachedToWindow} we attach the {@link Fragment} to a
* container.
* <li>{@link RecyclerView.Adapter#onViewRecycled} and
* {@link RecyclerView.Adapter#onFailedToRecycleView} we remove, save state, destroy the
* {@link Fragment}.
* </ul>
*/
public abstract class FragmentStateAdapter extends
RecyclerView.Adapter<FragmentViewHolder> implements StatefulAdapter {
private static final String KEY_PREFIX_FRAGMENT = "f#";
private static final String KEY_PREFIX_STATE = "s#";
private final LongSparseArray<Fragment> mFragments = new LongSparseArray<>();
private final LongSparseArray<Fragment.SavedState> mSavedStates = new LongSparseArray<>();
private final FragmentManager mFragmentManager;
public FragmentStateAdapter(@NonNull FragmentManager fragmentManager) {
mFragmentManager = fragmentManager;
super.setHasStableIds(true);
}
/**
* Provide a Fragment associated with the specified position.
*/
public abstract @NonNull Fragment getItem(int position);
@NonNull
@Override
public final FragmentViewHolder onCreateViewHolder(@NonNull ViewGroup parent, int viewType) {
return FragmentViewHolder.create(parent);
}
@Override
public final void onBindViewHolder(final @NonNull FragmentViewHolder holder, int position) {
Fragment fragment = getFragment(position);
if (holder.mFragment != fragment) {
/** There is no guarantee that {@link #onViewRecycled} happened since the last
* {@link #onBindViewHolder}, so performing a clean-up here. */
removeFragment(holder);
}
holder.mFragment = fragment;
/** Special case when {@link RecyclerView} decides to keep the {@link container}
* attached to the window, but not to the view hierarchy (i.e. parent is null) */
final FrameLayout container = holder.getContainer();
if (ViewCompat.isAttachedToWindow(container)) {
if (container.getParent() != null) {
throw new IllegalStateException("Design assumption violated.");
}
container.addOnLayoutChangeListener(new View.OnLayoutChangeListener() {
@Override
public void onLayoutChange(View v, int left, int top, int right, int bottom,
int oldLeft, int oldTop, int oldRight, int oldBottom) {
if (container.getParent() != null) {
container.removeOnLayoutChangeListener(this);
onViewAttachedToWindow(holder);
}
}
});
}
}
private Fragment getFragment(int position) {
long itemId = getItemId(position);
Fragment activeFragment = mFragments.get(itemId);
if (activeFragment != null) {
return activeFragment;
}
Fragment newFragment = getItem(position);
newFragment.setInitialSavedState(mSavedStates.get(itemId));
mFragments.put(itemId, newFragment);
return newFragment;
}
@Override
public final void onViewAttachedToWindow(@NonNull FragmentViewHolder holder) {
Fragment fragment = holder.mFragment;
FrameLayout container = holder.getContainer();
View view = fragment.getView();
/*
possible states:
- fragment: { added, notAdded }
- view: { created, notCreated }
- view: { attached, notAttached }
combinations:
- { f:added, v:created, v:attached } -> check if attached to the right container
- { f:added, v:created, v:notAttached} -> attach view to container
- { f:added, v:notCreated, v:attached } -> impossible
- { f:added, v:notCreated, v:notAttached} -> schedule callback for when created
- { f:notAdded, v:created, v:attached } -> illegal state
- { f:notAdded, v:created, v:notAttached } -> illegal state
- { f:notAdded, v:notCreated, v:attached } -> impossible
- { f:notAdded, v:notCreated, v:notAttached } -> add, create, attach
*/
// { f:notAdded, v:created, v:attached } -> illegal state
// { f:notAdded, v:created, v:notAttached } -> illegal state
if (!fragment.isAdded() && view != null) {
throw new IllegalStateException("Design assumption violated.");
}
// { f:added, v:notCreated, v:notAttached} -> schedule callback for when created
if (fragment.isAdded() && view == null) {
scheduleViewAttach(fragment, container);
return;
}
// { f:added, v:created, v:attached } -> check if attached to the right container
if (fragment.isAdded() && view.getParent() != null) {
if (view.getParent() != container) {
addViewToContainer(view, container);
}
return;
}
// { f:added, v:created, v:notAttached} -> attach view to container
if (fragment.isAdded()) {
addViewToContainer(view, container);
return;
}
// { f:notAdded, v:notCreated, v:notAttached } -> add, create, attach
scheduleViewAttach(fragment, container);
// TODO(b/122669030): this call might fail, so address with recovery steps
mFragmentManager.beginTransaction().add(fragment, "f" + holder.getItemId()).commitNow();
}
private void scheduleViewAttach(final Fragment fragment, final FrameLayout container) {
// After a config change, Fragments that were in FragmentManager will be recreated. Since
// ViewHolder container ids are dynamically generated, we opted to manually handle
// attaching Fragment views to containers. For consistency, we use the same mechanism for
// all Fragment views.
mFragmentManager.registerFragmentLifecycleCallbacks(
new FragmentManager.FragmentLifecycleCallbacks() {
@Override
public void onFragmentViewCreated(@NonNull FragmentManager fm,
@NonNull Fragment f, @NonNull View v,
@Nullable Bundle savedInstanceState) {
if (f == fragment) {
fm.unregisterFragmentLifecycleCallbacks(this);
addViewToContainer(v, container);
}
}
}, false);
}
@SuppressWarnings("WeakerAccess") // to avoid creation of a synthetic accessor
void addViewToContainer(@NonNull View v, FrameLayout container) {
if (container.getChildCount() > 1) {
throw new IllegalStateException("Design assumption violated.");
}
if (v.getParent() == container) {
return;
}
if (container.getChildCount() > 0) {
container.removeAllViews();
}
if (v.getParent() != null) {
((ViewGroup) v.getParent()).removeView(v);
}
container.addView(v);
}
@Override
public final void onViewRecycled(@NonNull FragmentViewHolder holder) {
removeFragment(holder);
}
@Override
public final boolean onFailedToRecycleView(@NonNull FragmentViewHolder holder) {
// This happens when a ViewHolder is in a transient state (e.g. during custom
// animation). We don't have sufficient information on how to clear up what lead to
// the transient state, so we are throwing away the ViewHolder to stay on the
// conservative side.
removeFragment(holder);
return false; // don't recycle the view
}
private void removeFragment(@NonNull FragmentViewHolder holder) {
removeFragment(holder.mFragment, holder.getItemId());
holder.getContainer().removeAllViews();
holder.mFragment = null;
}
/**
* Removes a Fragment and commits the operation.
*/
private void removeFragment(Fragment fragment, long itemId) {
FragmentTransaction fragmentTransaction = mFragmentManager.beginTransaction();
removeFragment(fragment, itemId, fragmentTransaction);
// TODO(b/122669030): this call might fail, so address with recovery steps
fragmentTransaction.commitNow();
}
/**
* Adds a remove operation to the transaction, but does not commit.
*/
private void removeFragment(Fragment fragment, long itemId,
@NonNull FragmentTransaction fragmentTransaction) {
if (fragment == null) {
return;
}
if (fragment.isAdded() && containsItem(itemId)) {
mSavedStates.put(itemId, mFragmentManager.saveFragmentInstanceState(fragment));
}
mFragments.remove(itemId);
fragmentTransaction.remove(fragment);
}
/**
* Default implementation works for collections that don't add, move, remove items.
* <p>
* TODO(b/122670460): add lint rule
* When overriding, also override {@link #containsItem(long)}.
* <p>
* If the item is not a part of the collection, return {@link RecyclerView#NO_ID}.
*
* @param position Adapter position
* @return stable item id {@link RecyclerView.Adapter#hasStableIds()}
*/
@Override
public long getItemId(int position) {
return position;
}
/**
* Default implementation works for collections that don't add, move, remove items.
* <p>
* TODO(b/122670460): add lint rule
* When overriding, also override {@link #getItemId(int)}
*/
public boolean containsItem(long itemId) {
return itemId >= 0 && itemId < getItemCount();
}
@Override
public final void setHasStableIds(boolean hasStableIds) {
throw new UnsupportedOperationException(
"Stable Ids are required for the adapter to function properly, and the adapter "
+ "takes care of setting the flag.");
}
@Override
public @NonNull Parcelable saveState() {
/** TODO(b/122670461): use custom {@link Parcelable} instead of Bundle to save space */
Bundle savedState = new Bundle(mFragments.size() + mSavedStates.size());
/** save references to active fragments */
for (int ix = 0; ix < mFragments.size(); ix++) {
long itemId = mFragments.keyAt(ix);
Fragment fragment = mFragments.get(itemId);
if (fragment != null && fragment.isAdded()) {
String key = createKey(KEY_PREFIX_FRAGMENT, itemId);
mFragmentManager.putFragment(savedState, key, fragment);
}
}
/** Write {@link mSavedStates) into a {@link Parcelable} */
for (int ix = 0; ix < mSavedStates.size(); ix++) {
long itemId = mSavedStates.keyAt(ix);
if (containsItem(itemId)) {
String key = createKey(KEY_PREFIX_STATE, itemId);
savedState.putParcelable(key, mSavedStates.get(itemId));
}
}
return savedState;
}
@Override
public void restoreState(@NonNull Parcelable savedState) {
if (!mSavedStates.isEmpty() || !mFragments.isEmpty()) {
throw new IllegalStateException(
"Expected the adapter to be 'fresh' while restoring state.");
}
Bundle bundle = (Bundle) savedState;
for (String key : bundle.keySet()) {
if (isValidKey(key, KEY_PREFIX_FRAGMENT)) {
long itemId = parseIdFromKey(key, KEY_PREFIX_FRAGMENT);
Fragment fragment = mFragmentManager.getFragment(bundle, key);
mFragments.put(itemId, fragment);
continue;
}
if (isValidKey(key, KEY_PREFIX_STATE)) {
long itemId = parseIdFromKey(key, KEY_PREFIX_STATE);
Fragment.SavedState state = bundle.getParcelable(key);
mSavedStates.put(itemId, state);
continue;
}
throw new IllegalArgumentException("Unexpected key in savedState: " + key);
}
}
// Helper function for dealing with save / restore state
private static @NonNull String createKey(@NonNull String prefix, long id) {
return prefix + id;
}
// Helper function for dealing with save / restore state
private static boolean isValidKey(@NonNull String key, @NonNull String prefix) {
return key.startsWith(prefix) && key.length() > prefix.length();
}
// Helper function for dealing with save / restore state
private static long parseIdFromKey(@NonNull String key, @NonNull String prefix) {
return Long.parseLong(key.substring(prefix.length()));
}
}