Merge "docs: Update JavaDoc ref links for UI training." into mnc-preview-docs

  <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>

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 <code>GridViewPager</code> element to the layout

of your activity and implement an adapter that provides a set of pages by extending

the <code>FragmentGridPagerAdapter</code> class.</p>

<p class="note"><strong>Note:</strong> The <em>GridViewPager</em> sample in the Android SDK

demonstrates how to use the <code>GridViewPager</code> layout in your apps. This sample is

located in the <code>android-sdk/samples/android-20/wearable/GridViewPager</code> directory.</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 <code>GridViewPager</code> element to your layout definition as follows:</p>

<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

<h2 id="implement-adapter">Implement a Page Adapter</h2>

<p>A page adapter provides a set of pages to populate a <code>GridViewPager</code> component. To

implement this adapter, you extend the <code>FragmentGridPageAdapter</code> class from the

Wearable UI Library</p>

<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>For example, the <em>GridViewPager</em> sample in the Android SDK contains

the following adapter implementation that provides a set of static cards with custom background

<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);

}

</pre>

<p>The picker calls <code>getFragment</code> and <code>getBackground</code> to retrieve the content

to display at each position of the grid:</p>

<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

    return fragment;

}

// Obtain the background image for the page at the specified position

// 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 ImageReference getBackground(int row, int column) {

    return ImageReference.forDrawable(BG_IMAGES[row % BG_IMAGES.length]);

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 <code>getRowCount</code> method tells the picker how many rows of content are

available, and the <code>getColumnCount</code> method tells the picker how many columns

of content are available for each of the rows.</p>

<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)

</pre>

<p>The adapter implementation details depend on your particular set of pages. Each page provided

by the adapter is of type <code>Fragment</code>. In this example, each page is a

<code>CardFragment</code> 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>

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=""/>

</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 <code>GridViewPager</code> component to

implement a 1D picker with only one row or only one column.</p>

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><code>GridViewPager</code> provides support for scrolling in cards whose content does not fit

<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 <code>getBackground()</code> method.

When users swipe to navigate across pages, <code>GridViewPager</code> applies parallax

and crossfade effects between different backgrounds automatically.</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

<code>GridViewPager</code> component:</p>

<a href="{@docRoot}reference/android/support/wearable/view/GridViewPager.html"><code>GridViewPager</code></a>

component:</p>

<pre>

<pre style="clear:both">

public class MainActivity extends Activity {

    @Override

This lesson shows you how to create cards in your Android Wear apps.</p>

<p>The Wearable UI Library provides implementations of cards specifically designed for wearable

devices. This library contains the <code>CardFrame</code> class, which wraps views inside

a card-styled frame with a white background, rounded corners, and a light-drop shadow.

<code>CardFrame</code> can only contain one direct child, usually a layout manager, to which

devices. This library contains the

<a href="{@docRoot}reference/android/support/wearable/view/CardFrame.html"><code>CardFrame</code></a>

class, which wraps views inside a card-styled frame with a white background, rounded corners, and a

light-drop shadow. A

<a href="{@docRoot}reference/android/support/wearable/view/CardFrame.html"><code>CardFrame</code></a>

instance can only contain one direct child, usually a layout manager, to which

you can add other views to customize the content inside the card.</p>

<p>You can add cards to your app in two ways:</p>

<ul>

  <li>Use or extend the <code>CardFragment</code> class.</li>

  <li>Add a card inside a <code>CardScrollView</code> in your layout.</li>

  <li>Use or extend the

  <a href="{@docRoot}reference/android/support/wearable/view/CardFragment.html"><code>CardFragment</code></a>

  class.</li>

  <li>Add a card inside a

  <a href="{@docRoot}reference/android/support/wearable/view/CardScrollView.html"><code>CardScrollView</code></a>

  instance in your layout.</li>

</ul>

<p class="note"><strong>Note:</strong> This lesson shows you how to add cards to Android Wear

<h2 id="card-fragment">Create a Card Fragment</h2>

<p>The <code>CardFragment</code> class provides a default card layout with a title, a

description, and an icon. Use this approach to add cards to your app if the default card layout

shown in figure 1 meets your needs.</p>

<p>The

<a href="{@docRoot}reference/android/support/wearable/view/CardFragment.html"><code>CardFragment</code></a>

class provides a default card layout with a title, a description, and an icon. Use this approach to

add cards to your app if the default card layout shown in figure 1 meets your needs.</p>

<img src="{@docRoot}wear/images/05_uilib.png" width="500" height="245" alt=""/>

<p class="img-caption"><strong>Figure 1.</strong> The default <code>CardFragment</code> layout.</p>

<p class="img-caption"><strong>Figure 1.</strong> The default

<a href="{@docRoot}reference/android/support/wearable/view/CardFragment.html"><code>CardFragment</code></a>

layout.</p>

<p>To add a <code>CardFragment</code> to your app:</p>

<p>To add a

<a href="{@docRoot}reference/android/support/wearable/view/CardFragment.html"><code>CardFragment</code></a>

instance to your app:</p>

<ol>

<li>In your layout, assign an ID to the element that contains the card</li>

<li>Create a <code>CardFragment</code> instance in your activity</li>

<li>Use the fragment manager to add the <code>CardFragment</code> instance to its container</li>

<li>Create a

<a href="{@docRoot}reference/android/support/wearable/view/CardFragment.html"><code>CardFragment</code></a>

instance in your activity</li>

<li>Use the fragment manager to add the

<a href="{@docRoot}reference/android/support/wearable/view/CardFragment.html"><code>CardFragment</code></a>

instance to its container</li>

</ol>

<p>The following sample code shows the code for the screen display shown in Figure 1:</p>

<p>The following sample code shows the code for the screen display shown in figure 1:</p>

<pre>

<android.support.wearable.view.BoxInsetLayout

</android.support.wearable.view.BoxInsetLayout>

</pre>

<p>The following code adds the <code>CardFragment</code> instance to the activity in Figure 1:</p>

<p>The following code adds the

<a href="{@docRoot}reference/android/support/wearable/view/CardFragment.html"><code>CardFragment</code></a>

instance to the activity in figure 1:</p>

<pre>

protected void onCreate(Bundle savedInstanceState) {

}

</pre>

<p>To create a card with a custom layout using <code>CardFragment</code>, extend this class

and override its <code>onCreateContentView</code> method.</p>

<p>To create a card with a custom layout using the

<a href="{@docRoot}reference/android/support/wearable/view/CardFragment.html"><code>CardFragment</code></a>

class, extend the class and override its

<a href="{@docRoot}reference/android/support/wearable/view/CardFragment.html#onCreateContentView(android.view.LayoutInflater, android.view.ViewGroup, android.os.Bundle)"><code>onCreateContentView</code></a>

method.</p>

<h2 id="card-layout">Add a CardFrame to Your Layout</h2>

approach when you want to define a custom layout for the card inside a layout definition file.</p>

<img src="{@docRoot}wear/images/04_uilib.png" width="500" height="248" alt=""/>

<p class="img-caption"><strong>Figure 2.</strong> Adding a <code>CardFrame</code> to your

layout.</p>

<p class="img-caption"><strong>Figure 2.</strong> Adding a

<a href="{@docRoot}reference/android/support/wearable/view/CardFrame.html"><code>CardFrame</code></a>

to your layout.</p>

<p>The following layout code sample demonstrates a vertical linear layout with two elements. You

can create more complex layouts to fit the needs of your app.</p>

</android.support.wearable.view.BoxInsetLayout>

</pre>

<p>The <code>CardScrollView</code> element in the example layout above lets you assign gravity to

<p>The

<a href="{@docRoot}reference/android/support/wearable/view/CardScrollView.html><code>&lt;CardScrollView&gt;</code></a>

element in the example layout above lets you assign gravity to

the card when its content is smaller than the container. This example aligns the card to the

bottom of the screen:</p>

}

</pre>

<p><code>CardScrollView</code> detects the shape of the screen and displays the card differently

<p>The

<a href="{@docRoot}reference/android/support/wearable/view/CardScrollView.html"><code>&lt;CardScrollView&gt;</code></a>

element detects the shape of the screen and displays the card differently

on round and square devices, using wider side margins on round screens. However,

placing the <code>CardScrollView</code> element inside a <code>BoxInsetLayout</code> and using the

<code>layout_box="bottom"</code> attribute is useful to align the card to the bottom of round

screens without cropping its content.</p>

placing the

<a href="{@docRoot}reference/android/supprot/wearable/view/CardScrollView.html"><code>&lt;CardScrollView&gt;</code></a>

element inside a

<a href="{@docRoot}reference/android/support/wearable/view/BoxInsetLayout.html"><code>&lt;BoxInsetLayout&gt;</code></a>

and using the <code>layout_box="bottom"</code> attribute is useful to align the card to the bottom

of round screens without cropping its content.</p>

<p>To show a confirmation timer when users complete an action in your app:</p>

<ol>

<li>Add a <code>DelayedConfirmationView</code> element to your layout.</li>

<li>Implement the <code>DelayedConfirmationListener</code> interface in your activity.</li>

<li>Add a

<a href="{@docRoot}reference/android/support/wearable/view/DelayedConfirmationView.html"><code>&lt;DelayedConfirmationView&gt;</code></a>

element to your layout.</li>

<li>Implement the

<a href="{@docRoot}reference/android/support/wearable/view/DelayedConfirmationView.DelayedConfirmationListener.html"><code>DelayedConfirmationListener</code></a>

interface in your activity.</li>

<li>Set the duration of the timer and start it when the user completes an action.</li>

</ol>

<p>Add the <code>DelayedConfirmationView</code> element to your layout as follows:</p>

<p>Add the

<a href="{@docRoot}reference/android/support/wearable/view/DelayedConfirmationView.html"><code>&lt;DelayedConfirmationView&gt;</code></a>

element to your layout as follows:</p>

<pre>

<android.support.wearable.view.DelayedConfirmationView

<h2 id="show-confirmation">Show Confirmation Animations</h2>

<p>To show a confirmation animation when users complete an action in your app, create an intent

that starts <code>ConfirmationActivity</code> from one of your activities. You can specify

one of the these animations with the <code>EXTRA_ANIMATION_TYPE</code> intent extra:</p>

that starts

<a href="{@docRoot}reference/android/support/wearable/activity/ConfirmationActivity.html"><code>ConfirmationActivity</code></a>

from one of your activities. You can specify

one of the these animations with the

<a href="{@docRoot}reference/android/support/wearable/activity/ConfirmationActivity.html#EXTRA_ANIMATION_TYPE"><code>EXTRA_ANIMATION_TYPE</code></a>

intent extra:</p>

<ul>

<li><code>SUCCESS_ANIMATION</code></li>

<li><code>FAILURE_ANIMATION</code></li>

<li><code>OPEN_ON_PHONE_ANIMATION</code></li>

<li><a href="{@docRoot}reference/android/support/wearable/activity/ConfirmationActivity.html#SUCCESS_ANIMATION"><code>SUCCESS_ANIMATION</code></a></li>

<li><a href="{@docRoot}reference/android/support/wearable/activity/ConfirmationActivity.html#FAILURE_ANIMATION"><code>FAILURE_ANIMATION</code></a></li>

<li><a href="{@docRoot}reference/android/support/wearable/activity/ConfirmationActivity.html#OPEN_ON_PHONE_ANIMATION"><code>OPEN_ON_PHONE_ANIMATION</code></a></li>

</ul>

<p>You can also add a message that appears under the confirmation icon.</p>

<p>To use the <code>ConfirmationActivity</code> in your app, first declare this activity in your

manifest file:</p>

<p>To use the

<a href="{@docRoot}reference/android/support/wearable/activity/ConfirmationActivity.html"><code>ConfirmationActivity</code></a>

in your app, first declare this activity in your manifest file:</p>

<pre>

<manifest>

startActivity(intent);

</pre>

<p>After showing the confirmation animation, <code>ConfirmationActivity</code> finishes and your

activity resumes.</p>

<p>After showing the confirmation animation,

<a href="{@docRoot}reference/android/support/wearable/activity/ConfirmationActivity.html"><code>ConfirmationActivity</code></a>

finishes and your activity resumes.</p>

<p>For more immersive experiences, like an app that can scroll a map in any direction, you can

disable the swipe to exit gesture in your app. However, if you disable it, you must implement

the long-press-to-dismiss UI pattern to let users exit your app using the

<code>DismissOverlayView</code> class from the Wearable UI Library.

You must also inform your users the first time they run your app that they can exit using

a long press.</p>

<a href="{@docRoot}reference/android/support/wearable/view/DismissOverlayView.html"><code>DismissOverlayView</code></a>

class from the Wearable UI Library. You must also inform your users the first time they run your app

that they can exit using a long press.</p>

<p>For design guidelines about exiting Android Wear activities, see

<a href="{@docRoot}design/wear/structure.html#Custom">Breaking out of the card</a>.</p>

<h2 id="long-press">Implement the Long Press to Dismiss Pattern</h2>

<p>To use the <code>DissmissOverlayView</code> class in your activity, add this element to

your layout definition such that it covers the whole screen and is placed above all other views.

For example:</p>

<p>To use the

<a href="{@docRoot}reference/android/support/wearable/view/DismissOverlayView.html"><code>DismissOverlayView</code></a>

class in your activity, add this element to your layout definition such that it covers the whole

screen and is placed above all other views.</p>

<p>The following example shows how to add the

<a href="{@docRoot}reference/android/support/wearable/view/DismissOverlayView.html"><code>&lt;DismissOverlayView&gt;</code></a>

element:</p>

<pre>

<FrameLayout

<FrameLayout>

</pre>

<p>In your activity, obtain the <code>DismissOverlayView</code> element and set some introductory

text. This text is shown to users the first time they run your app to inform them that they

can exit the app using a long press gesture. Then use a <code>GestureDetector</code> to detect

a long press:</p>

<p>In your activity, obtain the

<a href="{@docRoot}reference/android/support/wearable/view/DismissOverlayView.html"><code>&lt;DismissOverlayView&gt;</code></a>

element and set some introductory text. This text is shown to users the first time they run your app

to inform them that they can exit the app using a long press gesture. Then use a

<a href="{@docRoot}reference/android/view/GestureDetector.html"><code>GestureDetector</code></a>

to detect a long press:</p>

<pre>

public class WearActivity extends Activity {

}

</pre>

<p>When the system detects a long press gesture, <code>DismissOverlayView</code> shows an

<strong>Exit</strong> button, which terminates your activity if the user presses it.</p>

 No newline at end of file

<p>When the system detects a long press gesture, the

<a href="{@docRoot}reference/android/support/wearable/view/DismissOverlayView.html"><code>&lt;DismissOverlayView&gt;</code></a>

element shows an <strong>Exit</strong> button, which terminates your activity if the user presses

it.</p>

 No newline at end of file