page.title=UI Widgets @jd:body

In this document

RecyclerView
CardView

The support library in the Android L Developer Preview contains two new widgets, RecyclerView and CardView. Use these widgets to show complex lists and cards in your app. These widgets have material design styles and animations by default.

RecyclerView

RecyclerView is a more advanced version of ListView. This widget is a container for large sets of views that can be recycled and scrolled very efficiently. Use the RecyclerView widget when you have lists with elements that change dynamically.

RecyclerView is easy to use, because it provides:

A set of layout managers for positioning items
Default animations for common item operations

You also have the flexibility to define custom layout managers and animations for this widget.

To use the RecyclerView widget, you have to specify an adapter and a layout manager. An adapter provides a binding from a dataset to views that are displayed within a RecyclerView. For example, if your dataset is an array of strings displayed as TextView items, the layout manager asks the adapter to:

Set the text of an existing TextView to one of the strings in the dataset
Create new TextView objects
Determine the size of the dataset

To create an adapter, you extend the RecyclerView.Adapter class. The details of the implementation depend on the specifics of your dataset and the type of views. Fore more information, see the examples below.

Figure 1 - The RecyclerView widget.

A layout manager positions item views inside a RecyclerView and determines when to reuse item views that are no longer visible to the user. To reuse (or recycle) a view, a layout manager may ask the adapter to replace the content of the view with a different element from the dataset. Recycling views in this manner improves performance by avoiding the creation of unnecessary views or performing expensive findViewById lookups.

RecyclerView provides two layout managers you can use:

LinearLayoutManager shows the items in a vertically scrolling list.
GridLayoutManager shows the items in a rectangular grid.

To create a custom layout, you extend the RecyclerView.LayoutManager class.

Examples

To include a RecyclerView in your layout:

<!-- A RecyclerView with some commonly used attributes -->
<android.support.v7.widget.RecyclerView
    android:id="@+id/my_recycler_view"
    android:scrollbars="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

To get the RecyclerView object in your activity:

public class MyActivity extends ActionBarActivity {
    private RecyclerView mRecyclerView;
    private RecyclerView.Adapter mAdapter;
    private RecyclerView.LayoutManager mLayoutManager;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.my_activity);
        mRecyclerView = (RecyclerView) findViewById(R.id.my_recycler_view);

        // improve performance if the size is fixed
        mRecyclerView.setHasFixedSize(true);

        // use a linear layout manager
        mLayoutManager = new LinearLayoutManager(this);
        mRecyclerView.setLayoutManager(mLayoutManager);

        // specify an adapter (see also next example)
        mAdapter = new MyAdapter(myDataset);
        mRecyclerView.setAdapter(mAdapter);
    }
    ...
}

To create a simple adapter:

public class MyAdapter extends RecyclerView.Adapter<MyAdapter.ViewHolder> {
    private String[] mDataset;

    // Provide a reference to the type of views that you are using
    // (custom viewholder)
    public static class ViewHolder extends RecyclerView.ViewHolder {
        public TextView mTextView;
        public ViewHolder(TextView v) {
            super(v);
            mTextView = v;
        }
    }

    // Provide a suitable constructor (depends on the kind of dataset)
    public MyAdapter(String[] myDataset) {
        mDataset = myDataset;
    }

    // Create new views (invoked by the layout manager)
    @Override
    public MyAdapter.ViewHolder onCreateViewHolder(ViewGroup parent,
                                                   int viewType) {
        // create a new view
        View v = new TextView(parent.getContext());
        // set the view's size, margins, paddings and layout parameters
        ...
        ViewHolder vh = new ViewHolder(v);
        return vh;
    }

    // Replace the contents of a view (invoked by the layout manager)
    @Override
    public void onBindViewHolder(ViewHolder holder, int position) {
        // - get element from your dataset at this position
        // - replace the contents of the view with that element
        holder.mTextView.setText(mDataset[position]);

    }

    // Return the size of your dataset (invoked by the layout manager)
    @Override
    public int getItemCount() {
        return mDataset.length;
    }
}

CardView

CardView extends the FrameLayout class and lets you show information inside a card with optional rounded corners:

To set the corner radius in your layouts, use the android:cardCornerRadius attribute.
To set the corner radius in your code, use the CardView.setRadius method.

To set the background color of a card, use the android:cardBackgroundColor attribute.

To include a CardView in your layout:

<!-- A CardView that contains a TextView -->
<android.support.v7.widget.CardView
    android:id="@+id/card_view"
    android:layout_gravity="center"
    android:layout_width="200dp"
    android:layout_height="200dp"
    card_view:cardCornerRadius="4dp">

    <TextView
        android:id="@+id/info_text"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</android.support.v7.widget.CardView>