From f71f509af0047c154a67c136e8f57a4018663379 Mon Sep 17 00:00:00 2001 From: Joe Malin Date: Thu, 13 Feb 2014 10:39:47 -0800 Subject: Docs: New swipe-to-refresh training guide. Doc-in-progress inherited from xoogler's (unfinished) CL http://ag/427505 . See comments for staging location. Patch set 1 is the version inherited from the xoogler; PS2 is after my edits. Per a conversation with CB, I've removed the "ListFragment" doc, and just put in a note about that topic in the "add-swipe-refresh" doc. Change-Id: Id1a1294b15c5a7363f650ea13237948b0effbc40 --- docs/html/training/swipe/add-swipe-interface.jd | 135 ++++++++++++++++++ docs/html/training/swipe/images/swipe.mp4 | Bin 0 -> 411879 bytes docs/html/training/swipe/images/swipe_original.mp4 | Bin 0 -> 743388 bytes docs/html/training/swipe/index.jd | 91 ++++++++++++ .../html/training/swipe/respond-refresh-request.jd | 158 +++++++++++++++++++++ docs/html/training/training_toc.cs | 19 ++- 6 files changed, 402 insertions(+), 1 deletion(-) create mode 100644 docs/html/training/swipe/add-swipe-interface.jd create mode 100644 docs/html/training/swipe/images/swipe.mp4 create mode 100644 docs/html/training/swipe/images/swipe_original.mp4 create mode 100644 docs/html/training/swipe/index.jd create mode 100644 docs/html/training/swipe/respond-refresh-request.jd 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 + + +
+
+ + +

This lesson teaches you to

+
    +
  1. Add the SwipeRefreshLayout Widget +
  2. Add a Refresh Action to the Action Bar +
+ + +

You should also read

+ + +

Sample Apps

+ + + +
+
+ + +

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

+ +

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

+ +

Add the SwipeRefreshLayout Widget

+

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

+ +

+ 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}: +

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

+ 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 + "@android:id/list", 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 SwipeRefreshListFragment + sample app. +

+ +

Add a Refresh Action to the Action Bar

+ +

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

+ +

+ You should add the refresh action as a menu item, + rather than as a button, by setting the attribute + android:showAsAction=never. 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. +

+ +

+ The following code demonstrates how to add the swipe-to-refresh action to the + overflow area: +

+ +
<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>
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 Binary files /dev/null and b/docs/html/training/swipe/images/swipe.mp4 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 Binary files /dev/null and b/docs/html/training/swipe/images/swipe_original.mp4 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 + +
+
+ +

Dependencies and prerequisites

+
    +
  • Android 1.6 (API level 4) or later +
    • + +
  • Latest version of the Android v4 Support Library +
    • +
+ +

Sample Apps

+ + + +
+
+ +

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

+ +

+ Note: 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 Support Library Setup + document. +

+ +

Lessons

+ +
+
+ Adding Swipe-to-Refresh To Your + App +
+ +
+
+
+ +
+ +
+ To replay the movie, click on the device screen +
+
+
+ +
+ 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. +
+ +
+ Responding to a Refresh + Request +
+ +
+ Learn how to respond to the swipe-to-refresh gesture, and how to perform the + same update from an action bar action. +
+
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 + +
+
+ + +

This lesson teaches you to

+
    +
  1. Respond to the Refresh Gesture
    2. +
  2. Respond to the Refresh Action +
+ +

Sample App

+ + + + +
+
+ +

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

+ +

Respond to the Refresh Gesture

+ +

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

+ +

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

+ +

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

+ +

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

+ +

+ 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}: +

+ +
/*
+ * 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();
+        }
+    }
+);
+ +

Respond to the Refresh Action

+ +

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

+ +

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

+ +

The following code shows how to respond to the request action: +

+ +
/*
+ * 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);
+
+}
+ +

+ Note: When the user triggers a refresh with a swipe action as + described in Respond to the Refresh Gesture, + 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 other than 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. +

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." - +
  • +
    + Supporting Swipe-to-Refresh +
    + +