appunite / sspulltorefresh

Simple and highly customizable pull to refresh view

SSPullToRefresh

There are dozens of pull to refresh views. I've never found one I'm happy with. I always end up customizing one, so I decided to write one that's highly customizable. You can just write your content view and forget about the actual pull to refresh details.

If you're using SSPullToRefresh in your application, add it to the list.

Example Usage

// If automaticallyAdjustsScrollViewInsets is set to NO:
- (void)viewDidLoad {
   [super viewDidLoad];
   self.pullToRefreshView = [[SSPullToRefreshView alloc] initWithScrollView:self.tableView delegate:self];
}

// If automaticallyAdjustsScrollViewInsets is set to YES:
- (void)viewDidLayoutSubviews {
   if(self.pullToRefreshView == nil) {
      self.pullToRefreshView = [[SSPullToRefreshView alloc] initWithScrollView:self.tableView delegate:self];
   }
}

- (void)viewDidUnload {
   [super viewDidUnload];
   self.pullToRefreshView = nil;
}

- (void)refresh {
   [self.pullToRefreshView startLoading];
   // Load data...
   [self.pullToRefreshView finishLoading];
}

- (void)pullToRefreshViewDidStartLoading:(SSPullToRefreshView *)view {
   [self refresh];
}

I generally make a property called loading in my view controller and just set that to YES inside refresh. Then in my custom setter, return if it's already YES. When it changes states, it will call startLoading and make the network call. Then when the network activity finishes, it will set it to NO and the customer setter handles calling finishLoading and doing whatever else.

The fine folks at NSScreencast have an excellent episode on SSPullToRefresh and even implementing a custom content view with Core Graphics. Check it out.

Customizing

SSPullToRefresh view is highly customizable. All of the pulling logic, animations, etc are wrapped up for you in SSPullToRefreshView. It doesn't have any UI. Its contentView handles displaying the UI. By default, it sets up an instance of SSSimplePullToRefreshContentView as the contentView.

Provided Content Views

SSPullToRefreshDefaultContentView and SSPullToRefreshSimpleContentView are provided by SSPullToRefresh. By default SSPullToRefreshDefaultContentView is used if you do not provide a content view. To use the provided simple content view, simply set it:

pullToRefreshView.contentView = [[SSPullToRefreshSimpleContentView alloc] initWithFrame:CGRectZero];

Custom Content Views

You can simply subclass SSPullToRefreshDefaultContentView or implement your own view that conforms to SSPullToRefreshContentView. You must implement the following method:

- (void)setState:(SSPullToRefreshViewState)state withPullToRefreshView:(SSPullToRefreshView *)view

This method will get called whenever the state changes. Here are the possible states. It is recommended to implement UI for most of the states, but you can do whatever you want.

• SSPullToRefreshViewStateNormal (recommended) — Most will say "Pull to refresh" in this state
• SSPullToRefreshViewStateReady (recommended) — Most will say "Release to refresh" in this state
• SSPullToRefreshViewStateLoading (recommended) — The view is loading
• SSPullToRefreshViewStateClosing (optional) — The view has finished loading and is animating closed

You may also optionally implement this method:

- (void)setLastUpdatedAt:(NSDate *)date withPullToRefreshView:(SSPullToRefreshView *)view

Adding To Your Project

If you are using CocoaPods than just add next line to your Podfile:

pod 'SSPullToRefresh'

Now run pod install to install the dependency.

Manually

Download the source files or add it as a git submodule. Here's how to add it as a submodule:

$ cd YourProject
$ git submodule add https://github.com/soffes/sspulltorefresh.git Vendor/SSPullToRefresh

Add all of the Objective-C files to your project.

SSPullToRefresh uses Automatic Reference Counting (ARC). (I think you should use ARC by the way.) If your project doesn't use ARC, you will need to set the -fobjc-arc compiler flag on all of the SSPullToRefresh source files. To do this in Xcode, go to your active target and select the "Build Phases" tab. In the "Compiler Flags" column, set -fobjc-arc for each of the SSPullToRefresh source files.

Thanks

I took some inspiration from PullToRefreshView by chpwn, which is based on EGOTableViewPullRefresh, which is inspired by Tweetie's pull to refresh by Loren Brichter. And around we go.

Enjoy.