Readme.markdown

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

Carthage is the recommended way to install SSPullToRefresh. Add the following to your Cartfile:

github "soffes/sspulltorefresh"

You can also install with CocoaPods:

pod 'SSPullToRefresh'

For manual installation, I recommend adding the project as a subproject to your project or workspace and adding the framework as a target dependency.

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.