diff options
| -rw-r--r-- | docs/html/training/swipe/add-swipe-interface.jd | 135 | ||||
| -rw-r--r-- | docs/html/training/swipe/images/swipe.mp4 | bin | 0 -> 411879 bytes | |||
| -rw-r--r-- | docs/html/training/swipe/images/swipe_original.mp4 | bin | 0 -> 743388 bytes | |||
| -rw-r--r-- | docs/html/training/swipe/index.jd | 91 | ||||
| -rw-r--r-- | docs/html/training/swipe/respond-refresh-request.jd | 158 | ||||
| -rw-r--r-- | docs/html/training/training_toc.cs | 19 |
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 000000000000..ac15caf58db2 --- /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 Binary files differnew file mode 100644 index 000000000000..cd5c511d5f1c --- /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 Binary files differnew file mode 100644 index 000000000000..abdf08f746af --- /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 000000000000..17b4cf73b036 --- /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 000000000000..243b4a388d7e --- /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 3ee7ab7ca51d..862663eefa1c 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" |