1page.title=Adding Swipe-to-Refresh To Your App
2trainingnavtop=true
3@jd:body
4
5
6<div id="tb-wrapper">
7<div id="tb">
8
9<!-- table of contents -->
10<h2>This lesson teaches you to</h2>
11<ol>
12    <li><a href="#AddSwipeWidget">Add the SwipeRefreshLayout Widget</a>
13    <li><a href="#AddRefreshAction">Add a Refresh Action to the Action Bar</a>
14</ol>
15
16<!-- other docs (NOT javadocs) -->
17<h2>You should also read</h2>
18<ul>
19  <li>
20    <a href=
21    "{@docRoot}guide/topics/ui/accessibility/index.html">Accessibility</a>
22  </li>
23
24  <li>
25    <a href="{@docRoot}training/basics/actionbar/index.html">Adding the Action
26    Bar</a>
27  </li>
28</ul>
29
30<h2>Sample Apps</h2>
31
32<ul>
33    <li><a href="{@docRoot}samples/SwipeRefreshLayoutBasic/index.html">
34            SwipeRefreshLayoutBasic</a></li>
35    <li><a href="{@docRoot}samples/SwipeRefreshListFragment/index.html">
36            SwipeRefreshListFragment</a></li>
37</ul>
38
39</div>
40</div>
41
42
43<p>
44  The swipe-to-refresh user interface pattern is implemented entirely within
45  the {@link android.support.v4.widget.SwipeRefreshLayout} widget, which
46  detects the vertical swipe, displays a distinctive progress bar, and triggers
47  callback methods in your app. You enable this behavior
48  by adding the widget to your layout file as the parent of a {@link
49  android.widget.ListView} or {@link android.widget.GridView}, and implementing
50  the refresh behavior that gets invoked when the user swipes.
51</p>
52
53<p>
54  This lesson shows you how to add the widget to an existing layout. It also
55  shows you how to add a refresh action to the action bar overflow area, so
56  that users who may be unable to use the swipe gesture can trigger a manual
57  update with an external device.
58</p>
59
60<h2 id="AddSwipeWidget">Add the SwipeRefreshLayout Widget</h2>
61<p>
62  To add the swipe to refresh widget to an existing app, add {@link
63  android.support.v4.widget.SwipeRefreshLayout} as the parent
64  of a single {@link android.widget.ListView} or {@link
65  android.widget.GridView}. Remember that {@link
66  android.support.v4.widget.SwipeRefreshLayout} only supports a single {@link
67  android.widget.ListView} or {@link android.widget.GridView} child.
68</p>
69
70<p>
71  The following example demonstrates how to add the {@link
72  android.support.v4.widget.SwipeRefreshLayout} widget to an existing layout
73  file containing a {@link android.widget.ListView}:
74</p>
75
76<pre>&lt;android.support.v4.widget.SwipeRefreshLayout
77    xmlns:android="http://schemas.android.com/apk/res/android"
78    android:id="&#64;+id/swiperefresh"
79    android:layout_width="match_parent"
80    android:layout_height="match_parent"&gt;
81
82    &lt;ListView
83        android:id="&#64;android:id/list"
84        android:layout_width="match_parent"
85        android:layout_height="match_parent" /&gt;
86
87&lt;/android.support.v4.widget.SwipeRefreshLayout&gt;</pre>
88
89<p>
90  You can also use the {@link android.support.v4.widget.SwipeRefreshLayout}
91  widget with a {@link android.support.v4.app.ListFragment}. If the layout
92  contains a {@link android.widget.ListView} with the ID
93  <code>"@android:id/list"</code>, the swipe-to-refresh functionality is
94  automatically supported. However, explicitly declaring the {@link
95  android.widget.ListView} in this way supersedes the default {@link
96  android.support.v4.app.ListFragment} view structure. If you want to use the
97  default view structure, you will have to override parts of the {@link
98  android.support.v4.widget.SwipeRefreshLayout} and {@link
99  android.support.v4.app.ListFragment} behavior. For an example of how to do
100  this, see the <a href=
101  "{@docRoot}samples/SwipeRefreshListFragment/index.html">SwipeRefreshListFragment</a>
102  sample app.
103</p>
104
105<h2 id="AddRefreshAction">Add a Refresh Action to the Action Bar</h2>
106
107<p>
108  You should add a refresh action to your app's action bar to ensure that
109  users who may not be able to perform a swipe gesture can still trigger a
110  manual update. For example, users with accessibility issues can trigger
111  action bar actions using external devices, such as keyboards and D-pads.
112</p>
113
114<p>
115  You should add the refresh action as a menu item,
116  rather than as a button, by setting the attribute
117  <code>android:showAsAction=never</code>. If you display the action as a
118  button, users may assume that the refresh button action is different from the
119  swipe-to-refresh action. By making the refresh action less conspicuous in the
120  action bar, you can encourage users to perform manual updates with the swipe
121  gesture while still maintaining the accessible option in a place where D-pad
122  users would look for it.
123</p>
124
125<p>
126  The following code demonstrates how to add the swipe-to-refresh action to the
127  overflow area:
128</p>
129
130<pre>&lt;menu xmlns:android="http://schemas.android.com/apk/res/android" &gt;
131    &lt;item
132        android:id="&#64;+id/menu_refresh"
133        android:showAsAction="never"
134        android:title="&#64;string/menu_refresh"/&gt;
135&lt;/menu&gt;</pre>
136