1 page.title=Adding Swipe-to-Refresh To Your App 2 trainingnavtop=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><android.support.v4.widget.SwipeRefreshLayout 77 xmlns:android="http://schemas.android.com/apk/res/android" 78 android:id="@+id/swiperefresh" 79 android:layout_width="match_parent" 80 android:layout_height="match_parent"> 81 82 <ListView 83 android:id="@android:id/list" 84 android:layout_width="match_parent" 85 android:layout_height="match_parent" /> 86 87 </android.support.v4.widget.SwipeRefreshLayout></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><menu xmlns:android="http://schemas.android.com/apk/res/android" > 131 <item 132 android:id="@+id/menu_refresh" 133 android:showAsAction="never" 134 android:title="@string/menu_refresh"/> 135 </menu></pre> 136
