am 9ceea140: am fbd4af0f: Merge "Docs: New swipe-to-refresh training guide." into lmp-docs

* commit '9ceea140a3830794b202eec6be68a9a13e37c59f':
  Docs: New swipe-to-refresh training guide.

6 files changed, 402 insertions, 1 deletions

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>&lt;android.support.v4.widget.SwipeRefreshLayout
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:id="&#64;+id/swiperefresh"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"&gt;
+
+    &lt;ListView
+        android:id="&#64;android:id/list"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent" /&gt;
+
+&lt;/android.support.v4.widget.SwipeRefreshLayout&gt;</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>&lt;menu xmlns:android="http://schemas.android.com/apk/res/android" &gt;
+    &lt;item
+        android:id="&#64;+id/menu_refresh"
+        android:showAsAction="never"
+        android:title="&#64;string/menu_refresh"/&gt;
+&lt;/menu&gt;</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
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
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() {
+        &#64;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.
+ */
+&#64;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 @@ include the action bar on devices running Android 2.1 or higher."
               </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"