1page.title=Responding to a Refresh Request
2
3trainingnavtop=true
4@jd:body
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="#RespondRefresh">Respond to the Refresh Gesture</a></li>
13  <li><a href="#RespondAction">Respond to the Refresh Action</a>
14</ol>
15
16<h2>Sample App</h2>
17
18<ul>
19    <li><a href="{@docRoot}samples/SwipeRefreshLayoutBasic/index.html">
20            SwipeRefreshLayoutBasic</a></li>
21</ul>
22
23
24</div>
25</div>
26
27<p>
28  This lesson shows you how to update your app when the user requests a manual
29  refresh, whether the user triggers the refresh with a swipe gesture or by
30  using the action bar refresh action.
31</p>
32
33<h2 id="RespondRefresh">Respond to the Refresh Gesture</h2>
34
35<p>
36  When the user makes a swipe gesture, the system displays the progress
37  indicator and calls your app's callback method. Your callback method is
38  responsible for actually updating the app's data.
39</p>
40
41<p>
42  To respond to the refresh gesture in your app, implement the {@link
43  android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener} interface and
44  its {@link
45  android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener#onRefresh
46  onRefresh()} method. The {@link
47  android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener#onRefresh
48  onRefresh()} method is invoked when the user performs a swipe gesture.
49</p>
50
51<p>
52  You should put the code for the actual update
53  operation in a separate method, and call that update method from your {@link
54  android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener#onRefresh
55  onRefresh()} implementation. That way, you can use the same update method to
56  perform the update when the user triggers a refresh from the action bar.
57</p>
58
59<p>
60  Your update method calls {@link
61  android.support.v4.widget.SwipeRefreshLayout#setRefreshing
62  setRefreshing(false)} when it has finished updating the data. Calling this
63  method instructs the {@link android.support.v4.widget.SwipeRefreshLayout} to
64  remove the progress indicator and update the view contents.
65</p>
66
67<p>
68  For example, the following code implements {@link
69  android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener#onRefresh
70  onRefresh()} and invokes the method {@code myUpdateOperation()} to update the
71  data displayed by the {@link android.widget.ListView}:
72</p>
73
74<pre>/*
75 * Sets up a SwipeRefreshLayout.OnRefreshListener that is invoked when the user
76 * performs a swipe-to-refresh gesture.
77 */
78mySwipeRefreshLayout.setOnRefreshListener(
79    new SwipeRefreshLayout.OnRefreshListener() {
80        &#64;Override
81        public void onRefresh() {
82            Log.i(LOG_TAG, "onRefresh called from SwipeRefreshLayout");
83
84            // This method performs the actual data-refresh operation.
85            // The method calls setRefreshing(false) when it's finished.
86            myUpdateOperation();
87        }
88    }
89);</pre>
90
91<h2 id="RespondAction">Respond to the Refresh Action</h2>
92
93<p>
94  If the user requests a refresh by using the action bar, the system calls the
95  {@link android.support.v4.app.Fragment#onOptionsItemSelected
96  onOptionsItemSelected()} method. Your app should respond to this call by
97  displaying the progress indicator and refreshing the app's data.
98</p>
99
100<p>
101  To respond to the refresh action, override {@link
102  android.support.v4.app.Fragment#onOptionsItemSelected
103  onOptionsItemSelected()}. In your override method, trigger the {@link
104  android.support.v4.widget.SwipeRefreshLayout} progress indicator by calling
105  {@link android.support.v4.widget.SwipeRefreshLayout#setRefreshing
106  setRefreshing()} with the value {@code true}, then perform the update
107  operation. Once again, you should be doing the actual update in a separate
108  method, so the same method can be called whether the user triggers the update
109  with a swipe or by using the action bar. When the update has finished, call
110  {@link android.support.v4.widget.SwipeRefreshLayout#setRefreshing
111  setRefreshing(false)} to remove the refresh progress indicator.
112</p>
113
114<p>The following code shows how to respond to the request action:
115</p>
116
117<pre>/*
118 * Listen for option item selections so that we receive a notification
119 * when the user requests a refresh by selecting the refresh action bar item.
120 */
121&#64;Override
122public boolean onOptionsItemSelected(MenuItem item) {
123    switch (item.getItemId()) {
124
125        // Check if user triggered a refresh:
126        case R.id.menu_refresh:
127            Log.i(LOG_TAG, "Refresh menu item selected");
128
129            // Signal SwipeRefreshLayout to start the progress indicator
130            mySwipeRefreshLayout.setRefreshing(true);
131
132            // Start the refresh background task.
133            // This method calls setRefreshing(false) when it's finished.
134            myUpdateOperation();
135
136            return true;
137    }
138
139    // User didn't trigger a refresh, let the superclass handle this action
140    return super.onOptionsItemSelected(item);
141
142}</pre>
143
144<p class="note">
145  <strong>Note:</strong> When the user triggers a refresh with a swipe action as
146  described in <a href="#RespondRefresh">Respond to the Refresh Gesture</a>,
147  you do not need to call {@link
148  android.support.v4.widget.SwipeRefreshLayout#setRefreshing setRefreshing()}.
149  The {@link
150  android.support.v4.widget.SwipeRefreshLayout} widget takes care of displaying
151  the progress indicator and removing it when the update has finished. However,
152  if the update is triggered by any means <em>other than</em> a swipe gesture,
153  you need to explicitly turn the progress indicator on with {@link
154  android.support.v4.widget.SwipeRefreshLayout#setRefreshing setRefreshing()}.
155  The method which actually refreshes the data calls {@link
156  android.support.v4.widget.SwipeRefreshLayout#setRefreshing
157  setRefreshing(false)} to signal that the update is finished.
158</p>
159