/SVPullToRefresh

Give pull-to-refresh & infinite scrolling to any UIScrollView with 1 line of code.

Primary LanguageObjective-CMIT LicenseMIT

Upgrading from an earlier version?: On October 25th, a complete and overdue refactor of this class was pushed that fixes memory issues as well as adds new feature people have been asking for a long time. I tried my best to make this a seamless transition (you will get some deprecation warnings).

Important note if your project doesn’t use ARC: you must add the -fobjc-arc compiler flag to UIScrollView+SVPullToRefresh.m and UIScrollView+SVInfiniteScrolling.m in Target Settings > Build Phases > Compile Sources.

SVPullToRefresh + SVInfiniteScrolling

These UIScrollView categories makes it super easy to add pull-to-refresh and infinite scrolling fonctionalities to any UIScrollView (or any of its subclass). Instead of depending on delegates and/or subclassing UIViewController, SVPullToRefresh uses the Objective-C runtime to add the following 2 methods:

- (void)addPullToRefreshWithActionHandler:(void (^)(void))actionHandler;
- (void)addInfiniteScrollingWithActionHandler:(void (^)(void))actionHandler;

Installation

  • Drag the SVPullToRefresh/SVPullToRefresh folder into your project.
  • Add the QuartzCore framework to your project.
  • Import UIScrollView+SVPullToRefresh.h and/or UIScrollView+SVInfiniteScrolling.m

Usage

(see sample Xcode project in /Demo)

Adding Pull to Refresh

[tableView addPullToRefreshWithActionHandler:^{
    // prepend data to dataSource, insert cells at top of table view
    // call [tableView.pullToRefreshView stopAnimating] when done
}];

If you’d like to programmatically trigger the refresh (for instance in viewDidLoad), you can do so with:

[tableView triggerPullToRefresh];

You can temporarily hide the pull to refresh view by setting the showsPullToRefresh property:

tableView.showsPullToRefresh = NO;

Customization

The pull to refresh view can be customized using the following properties/methods:

@property (nonatomic, strong) UIColor *arrowColor;
@property (nonatomic, strong) UIColor *textColor;
@property (nonatomic, readwrite) UIActivityIndicatorViewStyle activityIndicatorViewStyle;

- (void)setTitle:(NSString *)title forState:(SVPullToRefreshState)state;
- (void)setSubtitle:(NSString *)subtitle forState:(SVPullToRefreshState)state;
- (void)setCustomView:(UIView *)view forState:(SVPullToRefreshState)state;

You can access these properties through your scroll view’s pullToRefreshView property.

For instance, you would set the arrowColor property using:

tableView.pullToRefreshView.arrowColor = [UIColor whiteColor];

Adding Infinite Scrolling

[tableView addInfiniteScrollingWithActionHandler:^{
    // append data to data source, insert new cells at the end of table view
}];

If you’d like to programmatically trigger the refresh (for instance in viewDidLoad), you can do so with:

[tableView triggerInfiniteScrolling];

You can temporarily hide the infinite scrolling view by setting the showsInfiniteScrolling property:

tableView.showsInfiniteScrolling = NO;

If you’d like to keep the infinite scrolling view around but disable the action handler and state changing:

tableView.infiniteScrollingView.enabled = NO;

When disabled, the `state` property will always return `SVInfiniteScrollingStateStopped`.

Customization

The infinite scrolling view can be customized using the following properties/methods:

@property (nonatomic, readwrite) UIActivityIndicatorViewStyle activityIndicatorViewStyle;

- (void)setCustomView:(UIView *)view forState:(SVInfiniteScrollingState)state;

You can access these properties through your scroll view’s infiniteScrollingView property.

Under the hood

SVPullToRefresh extends UIScrollView by adding new public methods as well as a dynamic properties (thanks @seb_morel!). It uses key-value observing to track the scrollView’s contentOffset, which removes the need for the view to be linked to the UIScrollViewDelegate protocol.

Credits

SVPullToRefresh is brought to you by Sam Vermette and contributors to the project. If you have feature suggestions or bug reports, feel free to help out by sending pull requests or by creating new issues. If you’re using SVPullToRefresh in your project, attribution would be nice.

Big thanks to @seb_morel for his Demistifying the Objective-C runtime talk, which permitted the level of abstraction found in SVPullToRefresh.

Hat tip to Loren Brichter for inventing such a great UI mechanism.