ActionBar-PullToRefresh provides an easy way to add a modern version of the pull-to-refresh interaction to your application.
Please note that this is not an update to Android-PullToRefresh, this has been created from new. You should think of this as Android-PullToRefresh's younger, leaner cousin.
Please note that this is currently in a preview state. This basically means that the API is not fixed and you should expect changes between releases.
There are two sample applications, the stock sample which uses the standard library and is therefore has a minSdkVersion of 14. There is also a sample which uses the ActionBarSherlock extra so has a minSdkVersion of 7.
ActionBar-PullToRefresh has in-built support for:
- AbsListView derivatives (ListView & GridView).
- ScrollView
- WebView
If the View you want to use is not listed above, you can easily add support in your own code by providing a ViewDelegate. See the ViewDelegate section below for more info.
You just need to create an instance of PullToRefreshAttacher, giving it the Activity and the View for which will scroll.
private PullToRefreshAttacher mPullToRefreshHelper;
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Get View for which the user will scroll…
View scrollableView = findViewById(R.id.blah);
// Create a PullToRefreshAttacher instance
mPullToRefreshHelper = new PullToRefreshAttacher(this);
// Set the Refreshable View and provide the refresh listener
mPullToRefreshAttacher.setRefreshableView(scrollableView, this);
}See the ListView sample for more info.
One thing to note is that the PullToRefreshAttacher needs to be created in the onCreate() phase of the Activity. If you plan on using this library with Fragments then the best practice is for your Activity to create the PullToRefreshAttacher, and then have your fragments retrieve it from the Activity.
An example is provided in the Fragment & Tabs sample.
There are many ways you can customise the pull-to-refresh experience to your needs. See the GridView sample for more info on all of these.
ViewDelegates provide support for handling scrollable Views. The main use of a ViewDelegate is to being able to tell when a scrollable view is scrolled to the top. There is currently inbuilt support for:
- AbsListView classes (through AbsListViewDelegate)
- ScrollView (through ScrollViewDelegate)
- WebView (through WebViewDelegate)
So what if you want the view you want to use a view which isn't in the list above? Well you can just provide your own ViewDelegate.
// Create a PullToRefresh Attacher
mPullToRefreshAttacher = new PullToRefreshAttacher(this);
// Create ViewDelegate which can handle your scrollable view.
// In this case we're creating a ficticious class
PullToRefreshAttacher.ViewDelegate delegate = new XYZViewDelegate();
// Set the Refreshable View, along with your ViewDelegate
mPullToRefreshAttacher.setRefreshableView(xyzView, delegate, listener);When instatiating a PullToRefreshAttacher you can provide an Options instance which contains a number of configuration elements:
headerLayout: Layout resource to be inflated as the header view (see below).headerTransformer: The HeaderTransformer for the heard view (see below).headerInAnimation: The animation resource which is used when the header view is shown.headerOutAnimation: The animation resource which is used when the header view is hidden.refreshScrollDistance: The vertical distance (percentage of the scrollable view height) that the user needs to scroll for a refresh to start.refreshOnUp: Whether to wait to start the refresh until when the user has lifted their finger.
HeaderTransformers are responsible for updating the header view to match the current state. If you do not provide a HeaderTransformer, there is a default implementation created for you called DefaultHeaderTransformer. This default implementation is what provides the default behaviour (growing progress bar, etc).
If you feel that the default header view layout does not provide what you require, you can provide your own which is inflated for you. For the majority of cases, you will probably want to provide your own HeaderTransformer as well, to update your custom layout.
For the standard library (APIv14+) add the following as a dependency in you pom.xml:
<dependency>
<groupId>com.github.chrisbanes.actionbarpulltorefresh</groupId>
<artifactId>library</artifactId>
<version>0.5</version>
</dependency>
If you're using ActionBarSherlock (APIv7+) add the following as a dependency in you pom.xml:
<dependency>
<groupId>com.github.chrisbanes.actionbarpulltorefresh</groupId>
<artifactId>extra-abs</artifactId>
<version>0.5</version>
</dependency>
Copyright 2013 Chris Banes
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.