+ 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. +
+ ++ 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.
+
+ 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 0000000000000..cd5c511d5f1c6 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 0000000000000..abdf08f746afb 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 0000000000000..17b4cf73b0369 --- /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 + +
+ 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. +
+ ++ 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. +
+ ++ 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();
+ }
+ }
+);
+
++ 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 3ee7ab7ca51d9..862663eefa1c6 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." - +