1page.title=Grid View
2parent.title=Layouts
3parent.link=layout-objects.html
4@jd:body
5<div id="qv-wrapper">
6<div id="qv">
7<h2>In this document</h2>
8  <ol>
9    <li><a href="#example">Example</a></li>
10  </ol>
11  <h2>Key classes</h2>
12  <ol>
13	<li>{@link android.widget.GridView}</li>
14	<li>{@link android.widget.ImageView}</li>
15	<li>{@link android.widget.BaseAdapter}</li>
16  	<li>{@link android.widget.AdapterView.OnItemClickListener}</li>
17  </ol>
18</div>
19</div>
20<p>{@link android.widget.GridView} is a {@link android.view.ViewGroup} that displays items in a
21two-dimensional,
22scrollable grid. The grid items are automatically inserted to the layout using a {@link
23android.widget.ListAdapter}.</p>
24
25<p>For an introduction to how you can dynamically insert views using an adapter, read
26<a href="{@docRoot}guide/topics/ui/declaring-layout.html#AdapterViews">Building Layouts with
27  an Adapter</a>.</p>
28
29<img src="{@docRoot}images/ui/gridview.png" alt="" />
30
31
32<h2 id="example">Example</h2>
33
34<p>In this tutorial, you'll create a grid of image thumbnails. When an item is selected, a
35toast message will display the position of the image.</p>
36
37
38<ol>
39  <li>Start a new project named <em>HelloGridView</em>.</li>
40  <li>Find some photos you'd like to use, or <a
41href="{@docRoot}shareables/sample_images.zip">download these sample images</a>. Save the image files
42into the project's
43<code>res/drawable/</code> directory.</li>
44  <li>Open the <code>res/layout/main.xml</code> file and insert the following:
45<pre>
46&lt;?xml version="1.0" encoding="utf-8"?>
47&lt;GridView xmlns:android="http://schemas.android.com/apk/res/android" 
48    android:id="@+id/gridview"
49    android:layout_width="fill_parent" 
50    android:layout_height="fill_parent"
51    android:columnWidth="90dp"
52    android:numColumns="auto_fit"
53    android:verticalSpacing="10dp"
54    android:horizontalSpacing="10dp"
55    android:stretchMode="columnWidth"
56    android:gravity="center"
57/>
58</pre>
59  <p>This {@link android.widget.GridView} will fill the entire screen. The attributes are rather
60self explanatory. For more information about valid attributes, see the {@link
61android.widget.GridView} reference.</p>
62</li>
63  <li>Open <code>HelloGridView.java</code> and insert the following code for the
64{@link android.app.Activity#onCreate(Bundle) onCreate()} method:
65<pre>
66public void onCreate(Bundle savedInstanceState) {
67    super.onCreate(savedInstanceState);
68    setContentView(R.layout.main);
69
70    GridView gridview = (GridView) findViewById(R.id.gridview);
71    gridview.setAdapter(new ImageAdapter(this));
72
73    gridview.setOnItemClickListener(new OnItemClickListener() {
74        public void onItemClick(AdapterView&lt;?> parent, View v, int position, long id) {
75            Toast.makeText(HelloGridView.this, "" + position, Toast.LENGTH_SHORT).show();
76        }
77    });
78}
79</pre>
80  <p>After the {@code main.xml} layout is set for the content view, the
81{@link android.widget.GridView} is captured from the layout with {@link
82android.app.Activity#findViewById(int)}. The {@link
83android.widget.GridView#setAdapter(T) setAdapter()} method then sets a custom adapter ({@code
84ImageAdapter}) as the source for all items to be displayed in the grid. The {@code ImageAdapter} is
85created in the next step.</p>
86<p>To do something when an item in the grid is clicked, the {@link
87android.widget.AdapterView#setOnItemClickListener(OnItemClickListener) setOnItemClickListener()}
88method is passed a new {@link android.widget.AdapterView.OnItemClickListener}. This anonymous
89instance defines the {@link
90android.widget.AdapterView.OnItemClickListener#onItemClick(AdapterView,View,int,long)
91onItemClick()} callback method to show a {@link android.widget.Toast} that displays the index
92position (zero-based) of the selected item (in a real world scenario, the position could be used to
93get the full sized
94image for some other task).</p>
95
96</li>
97<li>Create a new class called <code>ImageAdapter</code> that extends {@link
98android.widget.BaseAdapter}:
99<pre>
100public class ImageAdapter extends BaseAdapter {
101    private Context mContext;
102
103    public ImageAdapter(Context c) {
104        mContext = c;
105    }
106
107    public int getCount() {
108        return mThumbIds.length;
109    }
110
111    public Object getItem(int position) {
112        return null;
113    }
114
115    public long getItemId(int position) {
116        return 0;
117    }
118
119    // create a new ImageView for each item referenced by the Adapter
120    public View getView(int position, View convertView, ViewGroup parent) {
121        ImageView imageView;
122        if (convertView == null) {  // if it's not recycled, initialize some attributes
123            imageView = new ImageView(mContext);
124            imageView.setLayoutParams(new GridView.LayoutParams(85, 85));
125            imageView.setScaleType(ImageView.ScaleType.CENTER_CROP);
126            imageView.setPadding(8, 8, 8, 8);
127        } else {
128            imageView = (ImageView) convertView;
129        }
130
131        imageView.setImageResource(mThumbIds[position]);
132        return imageView;
133    }
134
135    // references to our images
136    private Integer[] mThumbIds = {
137            R.drawable.sample_2, R.drawable.sample_3,
138            R.drawable.sample_4, R.drawable.sample_5,
139            R.drawable.sample_6, R.drawable.sample_7,
140            R.drawable.sample_0, R.drawable.sample_1,
141            R.drawable.sample_2, R.drawable.sample_3,
142            R.drawable.sample_4, R.drawable.sample_5,
143            R.drawable.sample_6, R.drawable.sample_7,
144            R.drawable.sample_0, R.drawable.sample_1,
145            R.drawable.sample_2, R.drawable.sample_3,
146            R.drawable.sample_4, R.drawable.sample_5,
147            R.drawable.sample_6, R.drawable.sample_7
148    };
149}
150</pre>
151<p>First, this implements some required methods inherited from {@link
152android.widget.BaseAdapter}. The constructor and {@link
153android.widget.Adapter#getCount()} are self-explanatory. Normally, {@link
154android.widget.Adapter#getItem(int)} should return the actual object at the specified position in
155the adapter, but it's ignored for this example. Likewise, {@link
156android.widget.Adapter#getItemId(int)} should return the row id of the item, but it's not
157needed here.</p>
158
159<p>The first method necessary is {@link android.widget.Adapter#getView(int,View,ViewGroup)
160getView()}. This method creates a new {@link android.view.View} for each image added to the {@code
161ImageAdapter}. When this is called, a {@link android.view.View} is passed in, which is normally a
162recycled object (at least after this has been called once), so there's a check to see if the
163object is null. If it <em>is</em> null, an {@link android.widget.ImageView} is instantiated and
164configured with desired properties for the image presentation:</p>
165<ul>
166  <li>{@link android.view.View#setLayoutParams(ViewGroup.LayoutParams)} sets
167the height and width for the View&mdash;this ensures that, no matter the size of the drawable, each
168image is resized and cropped to fit in these dimensions, as appropriate.</li>
169  <li>{@link android.widget.ImageView#setScaleType(ImageView.ScaleType)} declares that images should
170be cropped toward the center (if necessary).</li>
171  <li>{@link android.widget.ImageView#setPadding(int,int,int,int)} defines the padding for all
172sides. (Note that, if the images have different aspect-ratios, then less
173padding will cause for more cropping of the image if it does not match
174the dimensions given to the ImageView.)</li>
175</ul>
176
177<p>If the {@link android.view.View} passed to {@link
178android.widget.Adapter#getView(int,View,ViewGroup) getView()} is <em>not</em> null, then the local
179{@link android.widget.ImageView} is initialized with the recycled {@link android.view.View}
180object.</p>
181
182<p>At the end of the {@link android.widget.Adapter#getView(int,View,ViewGroup) getView()} method,
183the {@code
184position} integer passed into the method is used to select an image from the {@code mThumbIds}
185array, which is set as the image resource for the {@link android.widget.ImageView}.</p>
186<p>All that's left is to define the {@code mThumbIds} array of drawable resources.</p>
187</li>
188<li>Run the application.</li>
189</ol>
190
191<p>Try experimenting with the behaviors of the {@link android.widget.GridView} and {@link
192android.widget.ImageView} elements by adjusting their properties. For example, instead of using
193{@link android.view.View#setLayoutParams(ViewGroup.LayoutParams)}, try using
194{@link android.widget.ImageView#setAdjustViewBounds(boolean)}. </p>
195
196
197