| page.title=Creating a 2D Picker |
| |
| @jd:body |
| |
| <div id="tb-wrapper"> |
| <div id="tb"> |
| <h2>This lesson teaches you to</h2> |
| <ol> |
| <li><a href="#add-page-grid">Add a Page Grid</a></li> |
| <li><a href="#implement-adapter">Implement a Page Adapter</a></li> |
| </ol> |
| <h2>Related Samples</h2> |
| <ul> |
| <li><a href="{@docRoot}samples/GridViewPager/index.html"> |
| GridViewPager</a></li> |
| </ul> |
| <h2>You should also read</h2> |
| <ul> |
| <li><a href="{@docRoot}design/wear/index.html">Android Wear Design Principles</a></li> |
| </ul> |
| </div> |
| </div> |
| |
| <p>The <a href="{@docRoot}design/wear/structure.html#2DPicker">2D Picker</a> pattern in Android |
| Wear allows users to navigate and choose from a set of items shown as pages. The Wearable UI |
| Library lets you easily implement this pattern using a page grid, which is a layout manager |
| that allows users to scroll vertically and horizontally through pages of data.</p> |
| |
| <p>To implement this pattern, you add a |
| <a href="{@docRoot}reference/android/support/wearable/view/GridViewPager.html"><code>GridViewPager</code></a> |
| element to the layout of your activity and implement an adapter that provides a set of pages by |
| extending the |
| <a href="{@docRoot}reference/android/support/wearable/view/FragmentGridPagerAdapter.html"><code>FragmentGridPagerAdapter</code></a> |
| class.</p> |
| |
| |
| <h2 id="add-page-grid">Add a Page Grid</h2> |
| |
| <p>Add a |
| <a href="{@docRoot}reference/android/support/wearable/view/GridViewPager.html"><code>GridViewPager</code></a> |
| element to your layout definition as follows:</p> |
| |
| <pre> |
| <android.support.wearable.view.GridViewPager |
| xmlns:android="http://schemas.android.com/apk/res/android" |
| android:id="@+id/pager" |
| android:layout_width="match_parent" |
| android:layout_height="match_parent" /> |
| </pre> |
| |
| <p>You can use any of the techniques described in |
| <a href="{@docRoot}training/wearables/ui/layouts.html">Defining Layouts</a> to ensure that |
| your 2D picker works on both round and square devices.</p> |
| |
| |
| <h2 id="implement-adapter">Implement a Page Adapter</h2> |
| |
| <p>A page adapter provides a set of pages to populate a |
| <a href="{@docRoot}reference/android/support/wearable/view/GridViewPager.html"><code>GridViewPager</code></a> |
| component. To implement this adapter, you extend the |
| <a href="{@docRoot}reference/android/support/wearable/view/FragmentGridPagerAdapter.html"><code>FragmentGridPagerAdapter</code></a> |
| class from the Wearable UI Library</p> |
| |
| <p>The following snippet shows how to provide a set of static cards with custom background |
| images:</p> |
| |
| <pre> |
| public class SampleGridPagerAdapter extends FragmentGridPagerAdapter { |
| |
| private final Context mContext; |
| private List<Row> mRows; |
| |
| public SampleGridPagerAdapter(Context ctx, FragmentManager fm) { |
| super(fm); |
| mContext = ctx; |
| } |
| |
| static final int[] BG_IMAGES = new int[] { |
| R.drawable.debug_background_1, ... |
| R.drawable.debug_background_5 |
| }; |
| |
| // A simple container for static data in each page |
| private static class Page { |
| // static resources |
| int titleRes; |
| int textRes; |
| int iconRes; |
| ... |
| } |
| |
| // Create a static set of pages in a 2D array |
| private final Page[][] PAGES = { ... }; |
| |
| // Override methods in FragmentGridPagerAdapter |
| ... |
| } |
| </pre> |
| |
| <p>The adapter calls |
| <a href="{@docRoot}reference/android/support/wearable/view/FragmentGridPagerAdapter.html#getFragment(int, int)"><code>getFragment()</code></a> |
| and |
| <a href="{@docRoot}reference/android/support/wearable/view/GridPagerAdapter.html#getBackgroundForRow(int)"><code>getBackgroundForRow()</code></a> |
| to retrieve the content to display for each row:</p> |
| |
| <pre> |
| // Obtain the UI fragment at the specified position |
| @Override |
| public Fragment getFragment(int row, int col) { |
| Page page = PAGES[row][col]; |
| String title = |
| page.titleRes != 0 ? mContext.getString(page.titleRes) : null; |
| String text = |
| page.textRes != 0 ? mContext.getString(page.textRes) : null; |
| CardFragment fragment = CardFragment.create(title, text, page.iconRes); |
| |
| // Advanced settings (card gravity, card expansion/scrolling) |
| fragment.setCardGravity(page.cardGravity); |
| fragment.setExpansionEnabled(page.expansionEnabled); |
| fragment.setExpansionDirection(page.expansionDirection); |
| fragment.setExpansionFactor(page.expansionFactor); |
| return fragment; |
| } |
| |
| // Obtain the background image for the row |
| @Override |
| public Drawable getBackgroundForRow(int row) { |
| return mContext.getResources().getDrawable( |
| (BG_IMAGES[row % BG_IMAGES.length]), null); |
| } |
| |
| </pre> |
| |
| <p>The following example shows how to retrieve the background to display for a specific page |
| in the grid: |
| </p> |
| |
| <pre> |
| // Obtain the background image for the specific page |
| @Override |
| public Drawable getBackgroundForPage(int row, int column) { |
| if( row == 2 && column == 1) { |
| // Place image at specified position |
| return mContext.getResources().getDrawable(R.drawable.bugdroid_large, null); |
| } else { |
| // Default to background image for row |
| return GridPagerAdapter.BACKGROUND_NONE; |
| } |
| } |
| </pre> |
| |
| <p>The |
| <a href="{@docRoot}reference/android/support/wearable/view/GridPagerAdapter.html#getRowCount()"><code>getRowCount()</code></a> |
| method tells the adapter how many rows of content are |
| available, and the |
| <a href="{@docRoot}reference/android/support/wearable/view/GridPagerAdapter.html#getColumnCount(int)"><code>getColumnCount()</code></a> |
| method tells the adapter how many columns of content are available for each of the rows.</p> |
| |
| <pre> |
| // Obtain the number of pages (vertical) |
| @Override |
| public int getRowCount() { |
| return PAGES.length; |
| } |
| |
| // Obtain the number of pages (horizontal) |
| @Override |
| public int getColumnCount(int rowNum) { |
| return PAGES[rowNum].length; |
| } |
| </pre> |
| |
| <p>The adapter implementation details depend on your particular set of pages. Each page provided |
| by the adapter is of type |
| <a href="{@docRoot}reference/android/app/Fragment.html"><code>Fragment</code></a>. |
| In this example, each page is a |
| <a href="{@docRoot}reference/android/support/wearable/view/CardFragment.html"><code>CardFragment</code></a> |
| instance that uses one of the default card layouts. However, you can combine different types of |
| pages in the same 2D picker, such as cards, action icons, and custom layouts depending on your use |
| cases.</p> |
| |
| <div style="float:right;margin-left:25px;width:250px"> |
| <img src="{@docRoot}wear/images/07_uilib.png" width="250" height="250" alt=""/> |
| <p class="img-caption" style="text-align:center"><strong>Figure 1:</strong> |
| The <em>GridViewPager</em> sample.</p> |
| </div> |
| |
| <p>Not all rows need to have the same number of pages. Notice that in this example the number of |
| colums is different for each row. You can also use a |
| <a href="{@docRoot}reference/android/support/wearable/view/GridViewPager.html"><code>GridViewPager</code></a> |
| component to implement a 1D picker with only one row or only one column.</p> |
| |
| <p>The |
| <a href="{@docRoot}reference/android/support/wearable/view/GridViewPager.html"><code>GridViewPager</code></a> |
| class provides support for scrolling in cards whose content does not fit |
| the device screen. This example configures each card to expand as required, so users can scroll |
| through the card's content. When users reach the end of a scrollable card, a swipe in the same |
| direction shows the next page on the grid, if one is available.</p> |
| |
| <p>You can specify a custom background for each page with the |
| <a href="{@docRoot}reference/android/support/wearable/view/GridPagerAdapter.html#getBackgroundForPage(int, int)"><code>getBackgroundForPage()</code></a> |
| method. When users swipe to navigate across pages, the |
| <a href="{@docRoot}reference/android/support/wearable/view/GridViewPager.html"><code>GridViewPager</code></a> |
| class applies parallax and crossfade effects between different backgrounds automatically.</p> |
| |
| <h3>Assign an adapter instance to the page grid</h3> |
| |
| <p>In your activity, assign an instance of your adapter implementation to the |
| <a href="{@docRoot}reference/android/support/wearable/view/GridViewPager.html"><code>GridViewPager</code></a> |
| component:</p> |
| |
| <pre style="clear:both"> |
| public class MainActivity extends Activity { |
| |
| @Override |
| protected void onCreate(Bundle savedInstanceState) { |
| super.onCreate(savedInstanceState); |
| setContentView(R.layout.activity_main); |
| ... |
| final GridViewPager pager = (GridViewPager) findViewById(R.id.pager); |
| pager.setAdapter(new SampleGridPagerAdapter(this, getFragmentManager())); |
| } |
| } |
| </pre> |