Merge "Docs: New swipe-to-refresh training guide." into lmp-docs
diff --git a/docs/html/training/swipe/add-swipe-interface.jd b/docs/html/training/swipe/add-swipe-interface.jd
new file mode 100644
index 0000000..ac15caf
--- /dev/null
+++ b/docs/html/training/swipe/add-swipe-interface.jd
@@ -0,0 +1,135 @@
+page.title=Adding Swipe-to-Refresh To Your App
+trainingnavtop=true
+@jd:body
+
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#AddSwipeWidget">Add the SwipeRefreshLayout Widget</a>
+ <li><a href="#AddRefreshAction">Add a Refresh Action to the Action Bar</a>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+<ul>
+ <li>
+ <a href=
+ "{@docRoot}guide/topics/ui/accessibility/index.html">Accessibility</a>
+ </li>
+
+ <li>
+ <a href="{@docRoot}training/basics/actionbar/index.html">Adding the Action
+ Bar</a>
+ </li>
+</ul>
+
+<h2>Sample Apps</h2>
+
+<ul>
+ <li><a href="{@docRoot}samples/SwipeRefreshLayoutBasic/index.html">
+ SwipeRefreshLayoutBasic</a></li>
+ <li><a href="{@docRoot}samples/SwipeRefreshListFragment/index.html">
+ SwipeRefreshListFragment</a></li>
+</ul>
+
+</div>
+</div>
+
+
+<p>
+ The swipe-to-refresh user interface pattern is implemented entirely within
+ the {@link android.support.v4.widget.SwipeRefreshLayout} widget, which
+ detects the vertical swipe, displays a distinctive progress bar, and triggers
+ callback methods in your app. You enable this behavior
+ by adding the widget to your layout file as the parent of a {@link
+ android.widget.ListView} or {@link android.widget.GridView}, and implementing
+ the refresh behavior that gets invoked when the user swipes.
+</p>
+
+<p>
+ This lesson shows you how to add the widget to an existing layout. It also
+ shows you how to add a refresh action to the action bar overflow area, so
+ that users who may be unable to use the swipe gesture can trigger a manual
+ update with an external device.
+</p>
+
+<h2 id="AddSwipeWidget">Add the SwipeRefreshLayout Widget</h2>
+<p>
+ To add the swipe to refresh widget to an existing app, add {@link
+ android.support.v4.widget.SwipeRefreshLayout} as the parent
+ of a single {@link android.widget.ListView} or {@link
+ android.widget.GridView}. Remember that {@link
+ android.support.v4.widget.SwipeRefreshLayout} only supports a single {@link
+ android.widget.ListView} or {@link android.widget.GridView} child.
+</p>
+
+<p>
+ The following example demonstrates how to add the {@link
+ android.support.v4.widget.SwipeRefreshLayout} widget to an existing layout
+ file containing a {@link android.widget.ListView}:
+</p>
+
+<pre><android.support.v4.widget.SwipeRefreshLayout
+ xmlns:android="http://schemas.android.com/apk/res/android"
+ android:id="@+id/swiperefresh"
+ android:layout_width="match_parent"
+ android:layout_height="match_parent">
+
+ <ListView
+ android:id="@android:id/list"
+ android:layout_width="match_parent"
+ android:layout_height="match_parent" />
+
+</android.support.v4.widget.SwipeRefreshLayout></pre>
+
+<p>
+ You can also use the {@link android.support.v4.widget.SwipeRefreshLayout}
+ widget with a {@link android.support.v4.app.ListFragment}. If the layout
+ contains a {@link android.widget.ListView} with the ID
+ <code>"@android:id/list"</code>, the swipe-to-refresh functionality is
+ automatically supported. However, explicitly declaring the {@link
+ android.widget.ListView} in this way supersedes the default {@link
+ android.support.v4.app.ListFragment} view structure. If you want to use the
+ default view structure, you will have to override parts of the {@link
+ android.support.v4.widget.SwipeRefreshLayout} and {@link
+ android.support.v4.app.ListFragment} behavior. For an example of how to do
+ this, see the <a href=
+ "{@docRoot}samples/SwipeRefreshListFragment/index.html">SwipeRefreshListFragment</a>
+ sample app.
+</p>
+
+<h2 id="AddRefreshAction">Add a Refresh Action to the Action Bar</h2>
+
+<p>
+ You should add a refresh action to your app's action bar to ensure that
+ users who may not be able to perform a swipe gesture can still trigger a
+ manual update. For example, users with accessibility issues can trigger
+ action bar actions using external devices, such as keyboards and D-pads.
+</p>
+
+<p>
+ You should add the refresh action as a menu item,
+ rather than as a button, by setting the attribute
+ <code>android:showAsAction=never</code>. If you display the action as a
+ button, users may assume that the refresh button action is different from the
+ swipe-to-refresh action. By making the refresh action less conspicuous in the
+ action bar, you can encourage users to perform manual updates with the swipe
+ gesture while still maintaining the accessible option in a place where D-pad
+ users would look for it.
+</p>
+
+<p>
+ The following code demonstrates how to add the swipe-to-refresh action to the
+ overflow area:
+</p>
+
+<pre><menu xmlns:android="http://schemas.android.com/apk/res/android" >
+ <item
+ android:id="@+id/menu_refresh"
+ android:showAsAction="never"
+ android:title="@string/menu_refresh"/>
+</menu></pre>
diff --git a/docs/html/training/swipe/images/swipe.mp4 b/docs/html/training/swipe/images/swipe.mp4
new file mode 100644
index 0000000..cd5c511
--- /dev/null
+++ b/docs/html/training/swipe/images/swipe.mp4
Binary files differ
diff --git a/docs/html/training/swipe/images/swipe_original.mp4 b/docs/html/training/swipe/images/swipe_original.mp4
new file mode 100644
index 0000000..abdf08f
--- /dev/null
+++ b/docs/html/training/swipe/images/swipe_original.mp4
Binary files differ
diff --git a/docs/html/training/swipe/index.jd b/docs/html/training/swipe/index.jd
new file mode 100644
index 0000000..17b4cf7
--- /dev/null
+++ b/docs/html/training/swipe/index.jd
@@ -0,0 +1,91 @@
+page.title=Supporting Swipe-to-Refresh
+trainingnavtop=true
+startpage=true
+
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>Dependencies and prerequisites</h2>
+<ul>
+ <li>Android 1.6 (API level 4) or later
+ </li>
+
+ <li>Latest version of the Android v4 <a href=
+ "{@docRoot}tools/support-library/index.html">Support Library</a>
+ </li>
+</ul>
+
+<h2>Sample Apps</h2>
+
+<ul>
+ <li><a href="{@docRoot}samples/SwipeRefreshLayoutBasic/index.html">
+ SwipeRefreshLayoutBasic</a></li>
+ <li><a href="{@docRoot}samples/SwipeRefreshListFragment/index.html">
+ SwipeRefreshListFragment</a></li>
+ <li><a href="{@docRoot}samples/SwipeRefreshMultipleViews/index.html">
+ SwipeRefreshMultipleViews</a></li>
+</ul>
+
+</div>
+</div>
+
+<p>
+ Even if your app automatically updates its content on a regular basis, you
+ can allow users to request manual updates as well. For example, a weather
+ forecasting app can allow users get the latest forecasts on demand. To
+ provide a standard user experience for requesting updates, the Android
+ platform includes the swipe-to-refresh design pattern, which allows users
+ to trigger an update with a vertical swipe.
+</p>
+
+<p class="note">
+ <strong>Note:</strong> This class requires the latest version of the Android
+ v4 Support Library APIs. If you have not used the Support Library before,
+ follow the instructions in the <a href=
+ "{@docRoot}tools/support-library/setup.html">Support Library Setup</a>
+ document.
+</p>
+
+<h2>Lessons</h2>
+
+<dl>
+ <dt>
+ <b><a href="add-swipe-interface.html">Adding Swipe-to-Refresh To Your
+ App</a></b>
+ </dt>
+
+ <dd>
+ <div style="width:290px;margin-right:35px;float:right">
+ <div class="framed-nexus5-port-span-5">
+ <video class="play-on-hover" autoplay alt=
+ "When the user performs a swipe gesture, the SwipeRefreshLayout widget displays a progress indicator until your app finishes updating its data.">
+ <!-- Preferred video size 216x384 (portrait) -->
+ <source src="images/swipe.mp4">
+ </video>
+ </div>
+
+ <div style="font-size:10pt;margin-left:20px;margin-bottom:30px">
+ <em>To replay the movie, click on the device screen</em>
+ </div>
+ </div>
+ </dd>
+
+ <dd>
+ Learn how to provide swipe-to-refresh support in a {@link
+ android.widget.ListView} or {@link android.widget.GridView}, and how to
+ provide an accessible refresh option using the action bar.
+ </dd>
+
+ <dt>
+ <b><a href="respond-refresh-request.html">Responding to a Refresh
+ Request</a></b>
+ </dt>
+
+ <dd>
+ Learn how to respond to the swipe-to-refresh gesture, and how to perform the
+ same update from an action bar action.
+ </dd>
+</dl>
diff --git a/docs/html/training/swipe/respond-refresh-request.jd b/docs/html/training/swipe/respond-refresh-request.jd
new file mode 100644
index 0000000..243b4a3
--- /dev/null
+++ b/docs/html/training/swipe/respond-refresh-request.jd
@@ -0,0 +1,158 @@
+page.title=Responding to a Refresh Request
+
+trainingnavtop=true
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#RespondRefresh">Respond to the Refresh Gesture</a></li>
+ <li><a href="#RespondAction">Respond to the Refresh Action</a>
+</ol>
+
+<h2>Sample App</h2>
+
+<ul>
+ <li><a href="{@docRoot}samples/SwipeRefreshLayoutBasic/index.html">
+ SwipeRefreshLayoutBasic</a></li>
+</ul>
+
+
+</div>
+</div>
+
+<p>
+ This lesson shows you how to update your app when the user requests a manual
+ refresh, whether the user triggers the refresh with a swipe gesture or by
+ using the action bar refresh action.
+</p>
+
+<h2 id="RespondRefresh">Respond to the Refresh Gesture</h2>
+
+<p>
+ When the user makes a swipe gesture, the system displays the progress
+ indicator and calls your app's callback method. Your callback method is
+ responsible for actually updating the app's data.
+</p>
+
+<p>
+ To respond to the refresh gesture in your app, implement the {@link
+ android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener} interface and
+ its {@link
+ android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener#onRefresh
+ onRefresh()} method. The {@link
+ android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener#onRefresh
+ onRefresh()} method is invoked when the user performs a swipe gesture.
+</p>
+
+<p>
+ You should put the code for the actual update
+ operation in a separate method, and call that update method from your {@link
+ android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener#onRefresh
+ onRefresh()} implementation. That way, you can use the same update method to
+ perform the update when the user triggers a refresh from the action bar.
+</p>
+
+<p>
+ Your update method calls {@link
+ android.support.v4.widget.SwipeRefreshLayout#setRefreshing
+ setRefreshing(false)} when it has finished updating the data. Calling this
+ method instructs the {@link android.support.v4.widget.SwipeRefreshLayout} to
+ remove the progress indicator and update the view contents.
+</p>
+
+<p>
+ For example, the following code implements {@link
+ android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener#onRefresh
+ onRefresh()} and invokes the method {@code myUpdateOperation()} to update the
+ data displayed by the {@link android.widget.ListView}:
+</p>
+
+<pre>/*
+ * Sets up a SwipeRefreshLayout.OnRefreshListener that is invoked when the user
+ * performs a swipe-to-refresh gesture.
+ */
+mySwipeRefreshLayout.setOnRefreshListener(
+ new SwipeRefreshLayout.OnRefreshListener() {
+ @Override
+ public void onRefresh() {
+ Log.i(LOG_TAG, "onRefresh called from SwipeRefreshLayout");
+
+ // This method performs the actual data-refresh operation.
+ // The method calls setRefreshing(false) when it's finished.
+ myUpdateOperation();
+ }
+ }
+);</pre>
+
+<h2 id="RespondAction">Respond to the Refresh Action</h2>
+
+<p>
+ If the user requests a refresh by using the action bar, the system calls the
+ {@link android.support.v4.app.Fragment#onOptionsItemSelected
+ onOptionsItemSelected()} method. Your app should respond to this call by
+ displaying the progress indicator and refreshing the app's data.
+</p>
+
+<p>
+ To respond to the refresh action, override {@link
+ android.support.v4.app.Fragment#onOptionsItemSelected
+ onOptionsItemSelected()}. In your override method, trigger the {@link
+ android.support.v4.widget.SwipeRefreshLayout} progress indicator by calling
+ {@link android.support.v4.widget.SwipeRefreshLayout#setRefreshing
+ setRefreshing()} with the value {@code true}, then perform the update
+ operation. Once again, you should be doing the actual update in a separate
+ method, so the same method can be called whether the user triggers the update
+ with a swipe or by using the action bar. When the update has finished, call
+ {@link android.support.v4.widget.SwipeRefreshLayout#setRefreshing
+ setRefreshing(false)} to remove the refresh progress indicator.
+</p>
+
+<p>The following code shows how to respond to the request action:
+</p>
+
+<pre>/*
+ * Listen for option item selections so that we receive a notification
+ * when the user requests a refresh by selecting the refresh action bar item.
+ */
+@Override
+public boolean onOptionsItemSelected(MenuItem item) {
+ switch (item.getItemId()) {
+
+ // Check if user triggered a refresh:
+ case R.id.menu_refresh:
+ Log.i(LOG_TAG, "Refresh menu item selected");
+
+ // Signal SwipeRefreshLayout to start the progress indicator
+ mySwipeRefreshLayout.setRefreshing(true);
+
+ // Start the refresh background task.
+ // This method calls setRefreshing(false) when it's finished.
+ myUpdateOperation();
+
+ return true;
+ }
+
+ // User didn't trigger a refresh, let the superclass handle this action
+ return super.onOptionsItemSelected(item);
+
+}</pre>
+
+<p class="note">
+ <strong>Note:</strong> When the user triggers a refresh with a swipe action as
+ described in <a href="#RespondRefresh">Respond to the Refresh Gesture</a>,
+ you do not need to call {@link
+ android.support.v4.widget.SwipeRefreshLayout#setRefreshing setRefreshing()}.
+ The {@link
+ android.support.v4.widget.SwipeRefreshLayout} widget takes care of displaying
+ the progress indicator and removing it when the update has finished. However,
+ if the update is triggered by any means <em>other than</em> a swipe gesture,
+ you need to explicitly turn the progress indicator on with {@link
+ android.support.v4.widget.SwipeRefreshLayout#setRefreshing setRefreshing()}.
+ The method which actually refreshes the data calls {@link
+ android.support.v4.widget.SwipeRefreshLayout#setRefreshing
+ setRefreshing(false)} to signal that the update is finished.
+</p>
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs
index 3ee7ab7..862663e 100644
--- a/docs/html/training/training_toc.cs
+++ b/docs/html/training/training_toc.cs
@@ -1195,7 +1195,24 @@
</li>
</ul>
</li>
-
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>training/swipe/index.html"
+ description=
+ "How to modify your app's layout to support manual content updates triggered by the
+ swipe-to-refresh gesture."
+ >Supporting Swipe-to-Refresh</a>
+ </div>
+ <ul>
+ <li>
+ <a href="<?cs var:toroot ?>training/swipe/add-swipe-interface.html"
+ >Adding Swipe-to-Refresh To Your App</a></li>
+ <li>
+ <a href="<?cs var:toroot ?>training/swipe/respond-refresh-request.html"
+ >Responding to a Refresh Gesture</a>
+ </li>
+ </ul>
+ </li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>training/search/index.html"