/* * Copyright (C) 2017 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.recyclerview.extensions; import android.arch.lifecycle.LiveData; import android.support.annotation.RestrictTo; import android.support.v7.util.DiffUtil; import android.support.v7.util.ListUpdateCallback; import android.support.v7.widget.RecyclerView; import java.util.List; /** * Helper object for displaying a List in {@link RecyclerView.Adapter RecyclerView.Adapter}, which * signals the adapter of changes when the List is changed by computing changes with DiffUtil in the * background. *
* For simplicity, the {@link ListAdapter} wrapper class can often be used instead of the * helper directly. This helper class is exposed for complex cases, and where overriding an adapter * base class to support List diffing isn't convenient. *
* The ListAdapterHelper can take a {@link LiveData} of List and present the data simply for an * adapter. It computes differences in List contents via DiffUtil on a background thread as new * Lists are received. *
* It provides a simple list-like API with {@link #getItem(int)} and {@link #getItemCount()} for an * adapter to acquire and present data objects. *
* A complete usage pattern with Room would look like this: *
* {@literal @}Dao * interface UserDao { * {@literal @}Query("SELECT * FROM user ORDER BY lastName ASC") * public abstract LiveData<List<User>> usersByLastName(); * } * * class MyViewModel extends ViewModel { * public final LiveData<List<User>> usersList; * public MyViewModel(UserDao userDao) { * usersList = userDao.usersByLastName(); * } * } * * class MyActivity extends AppCompatActivity { * {@literal @}Override * public void onCreate(Bundle savedState) { * super.onCreate(savedState); * MyViewModel viewModel = ViewModelProviders.of(this).get(MyViewModel.class); * RecyclerView recyclerView = findViewById(R.id.user_list); * UserAdapter<User> adapter = new UserAdapter(); * viewModel.usersList.observe(this, list -> adapter.setList(list)); * recyclerView.setAdapter(adapter); * } * } * * class UserAdapter extends RecyclerView.Adapter<UserViewHolder> { * private final ListAdapterHelper<User> mHelper; * public UserAdapter(ListAdapterHelper.Builder<User> builder) { * mHelper = new ListAdapterHelper(this, User.DIFF_CALLBACK); * } * {@literal @}Override * public int getItemCount() { * return mHelper.getItemCount(); * } * public void setList(List<User> list) { * mHelper.setList(list); * } * {@literal @}Override * public void onBindViewHolder(UserViewHolder holder, int position) { * User user = mHelper.getItem(position); * holder.bindTo(user); * } * public static final DiffCallback<User> DIFF_CALLBACK = new DiffCallback<User>() { * {@literal @}Override * public boolean areItemsTheSame( * {@literal @}NonNull User oldUser, {@literal @}NonNull User newUser) { * // User properties may have changed if reloaded from the DB, but ID is fixed * return oldUser.getId() == newUser.getId(); * } * {@literal @}Override * public boolean areContentsTheSame( * {@literal @}NonNull User oldUser, {@literal @}NonNull User newUser) { * // NOTE: if you use equals, your object must properly override Object#equals() * // Incorrectly returning false here will result in too many animations. * return oldUser.equals(newUser); * } * } * }* * @param
* If a List is already present, a diff will be computed asynchronously on a background thread.
* When the diff is computed, it will be applied (dispatched to the {@link ListUpdateCallback}),
* and the new List will be swapped in.
*
* @param newList The new List.
*/
@SuppressWarnings("WeakerAccess")
public void setList(final List