πŸ“– A simple, highly informative page view controller.
Swift Ruby Other
Latest commit 814f1ac Nov 13, 2017 @msaps msaps Update README.md

README.md

Pageboy

Build Status Swift 4 CocoaPods Platforms Carthage compatible codecov GitHub release

TL;DR UIPageViewController done properly.

Pageboy is a simple, highly informative page view controller.

Features

  • Simplified data source management.
  • Enhanced delegation; featuring exact relative positional data and reliable updates.
  • Infinite scrolling support.
  • Automatic timer-based page transitioning.
  • Support for custom page transitions.

Requirements

Pageboy requires iOS 8.0 / tvOS 10.0 and Swift 4.0 or above.

Installation

CocoaPods

Pageboy is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'Pageboy', '~> 2.0'

And run pod install.

Carthage

Pageboy is available through Carthage. Simply install carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

Add Pageboy to your Cartfile:

github "uias/Pageboy" ~> 2.0

Usage

Getting Started

  1. Create an instance of a PageboyViewController and provide it with a PageboyViewControllerDataSource.
class PageViewController: PageboyViewController, PageboyViewControllerDataSource {

	override func viewDidLoad() {
		super.viewDidLoad()

		self.dataSource = self
	}
}
  1. Implement the PageboyViewControllerDataSource functions.
func numberOfViewControllers(in pageboyViewController: PageboyViewController) -> Int {
    return viewControllers.count
}
    
func viewController(for pageboyViewController: PageboyViewController,
                    at index: PageboyViewController.PageIndex) -> UIViewController? {
    return viewControllers[index]
}
    
func defaultPage(for pageboyViewController: PageboyViewController) -> PageboyViewController.Page? {
    return nil
}
  1. Enjoy.

Delegation

UIPageViewController doesn't provide the most useful delegate methods for detecting where you are when paging; this is where Pageboy comes in. PageboyViewControllerDelegate provides a number of functions for being able to detect where the page view controller is, and where it's headed.

willScrollToPageAtIndex

Called when the page view controller is about to embark on a transition to a new page.

func pageboyViewController(_ pageboyViewController: PageboyViewController,
                           willScrollToPageAt index: Int,
                           direction: PageboyViewController.NavigationDirection,
                           animated: Bool)

didScrollToPosition

Called when the page view controller was scrolled to a relative position along the way transitioning to a new page. Also provided is the direction of the transition.

func pageboyViewController(_ pageboyViewController: PageboyViewController,
                           didScrollTo position: CGPoint,
                           direction: PageboyViewController.NavigationDirection,
                           animated: Bool)

didScrollToPage

Called when the page view controller did successfully complete a scroll transition to a page.

func pageboyViewController(_ pageboyViewController: PageboyViewController,
                           didScrollToPageAt index: Int,
                           direction: PageboyViewController.NavigationDirection,
                           animated: Bool)

didReload

Called when the page view controller reloads its child view controllers.

func pageboyViewController(_ pageboyViewController: PageboyViewController,
                           didReloadWith currentViewController: UIViewController,
                           currentPageIndex: PageboyViewController.PageIndex)

Other useful stuff

  • reloadPages - Reload the view controllers in the page view controller. (Refreshes the data source).

     public func reloadPages()
  • scrollToPage - Scroll the page view controller to a new page programatically.

     public func scrollToPage(_ pageIndex: PageIndex,
                                animated: Bool,
                                completion: PageTransitionCompletion? = nil)
  • isScrollEnabled - Whether or not scrolling is allowed on the page view controller.

  • isInfiniteScrollEnabled - Whether the page view controlelr should infinitely scroll at the end of page ranges.

  • currentViewController - The currently visible view controller if it exists.

  • currentPosition - The exact current relative position of the page view controller.

  • currentIndex - The index of the currently visible page.

Transitioning

Pageboy also provides custom animated transition support. This can be customised via the .transition property on PageboyViewController.

pageboyViewController.transition = Transition(style: .push, duration: 1.0)

The following styles are available:

  • .push
  • .fade
  • .moveIn
  • .reveal

Auto Scrolling

PageboyAutoScroller is available to set up timer based automatic scrolling of the PageboyViewController:

pageboyViewController.autoScroller.enable()

Support for custom intermission duration and other scroll behaviors is also available.

About

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/uias/Pageboy.

License

The library is available as open source under the terms of the MIT License.