blob: ac15caf58db2850fdbe69b528d32a07e99b747ed [file] [log] [blame]
page.title=Adding Swipe-to-Refresh To Your App
<div id="tb-wrapper">
<div id="tb">
<!-- table of contents -->
<h2>This lesson teaches you to</h2>
<li><a href="#AddSwipeWidget">Add the SwipeRefreshLayout Widget</a>
<li><a href="#AddRefreshAction">Add a Refresh Action to the Action Bar</a>
<!-- other docs (NOT javadocs) -->
<h2>You should also read</h2>
<a href=
<a href="{@docRoot}training/basics/actionbar/index.html">Adding the Action
<h2>Sample Apps</h2>
<li><a href="{@docRoot}samples/SwipeRefreshLayoutBasic/index.html">
<li><a href="{@docRoot}samples/SwipeRefreshListFragment/index.html">
The swipe-to-refresh user interface pattern is implemented entirely within
the {@link} 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.
<h2 id="AddSwipeWidget">Add the SwipeRefreshLayout Widget</h2>
To add the swipe to refresh widget to an existing app, add {@link} as the parent
of a single {@link android.widget.ListView} or {@link
android.widget.GridView}. Remember that {@link} only supports a single {@link
android.widget.ListView} or {@link android.widget.GridView} child.
The following example demonstrates how to add the {@link} widget to an existing layout
file containing a {@link android.widget.ListView}:
android:layout_height="match_parent" /&gt;
You can also use the {@link}
widget with a {@link}. 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} view structure. If you want to use the
default view structure, you will have to override parts of the {@link} and {@link} behavior. For an example of how to do
this, see the <a href=
sample app.
<h2 id="AddRefreshAction">Add a Refresh Action to the Action Bar</h2>
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
<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.
The following code demonstrates how to add the swipe-to-refresh action to the
overflow area:
<pre>&lt;menu xmlns:android="" &gt;