docs/html/preview/material/ui-widgets.jd

page.title=UI Widgets

@jd:body


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


<h2  style="margin-top:35px">RecyclerView</h2>

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

<p><code>RecyclerView</code> is easy to use, because it provides:</p>

<ul>
  <li>A set of layout managers for positioning items</li>
  <li>Default animations for common item operations</li>
</ul>

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

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

<ul>
  <li>Set the text of an existing <code>TextView</code> to one of the strings in the dataset</li>
  <li>Create new <code>TextView</code> objects</li>
  <li>Determine the size of the dataset</li>
</ul>

<p>To create an adapter, you extend the <code>RecyclerView.Adapter</code> 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.</p>

<img src="/preview/material/images/RecyclerView.png" alt="" id="figure1" style="width:550px"/>
<p class="img-caption">
  <strong>Figure 1</strong> - The <code>RecyclerView</code> widget.
</p>

<p>A <strong>layout manager</strong> positions item views inside a <code>RecyclerView</code> and
determines when to reuse item views that are no longer visible to the user. To reuse (or
<em>recycle</em>) 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
<code>findViewById</code> lookups.
</p>

<p><code>RecyclerView</code> provides two layout managers you can use:</p>

<ul>
  <li><code>LinearLayoutManager</code> shows the items in a vertically scrolling list.</li>
  <li><code>GridLayoutManager</code> shows the items in a rectangular grid.</li>
</ul>

<p>To create a custom layout, you extend the <code>RecyclerView.LayoutManager</code> class.</p>

<h3 style="margin-top:30px">Examples</h3>

<p>To include a <code>RecyclerView</code> in your layout:</p>

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

<p>To get the <code>RecyclerView</code> object in your activity:</p>

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

    &#64;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);
    }
    ...
}
</pre>

<p>To create a simple adapter:</p>

<pre>
public class MyAdapter extends RecyclerView.Adapter&lt;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)
    &#64;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)
    &#64;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)
    &#64;Override
    public int getItemCount() {
        return mDataset.length;
    }
}
</pre>


<h2 style="margin-top:35px">CardView</h2>

<p><code>CardView</code> extends the <code>FrameLayout</code> class and lets you show information
inside a card with optional rounded corners:</p>

<ul>
  <li>To set the corner radius in your layouts, use the <code>android:cardCornerRadius</code>
  attribute.</li>
  <li>To set the corner radius in your code, use the <code>CardView.setRadius</code> method.</li>
</ul>

<p>To set the background color of a card, use the <code>android:cardBackgroundColor</code>
attribute.</p>

<p>To include a <code>CardView</code> in your layout:</p>

<pre>
&lt;!-- A CardView that contains a TextView -->
&lt;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">

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