A simple, highly informative page view controller.
Swift Ruby Other
Latest commit 435c1e2 Jun 24, 2017 @msaps msaps Merge branch 'release/1.3.1'

README.md

Pageboy

Build Status Swift 3.1 CocoaPods 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.

Installation

CocoaPods

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

pod 'Pageboy'

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" 

Requirements

Pageboy requires iOS 8.0 or above.

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 viewControllers(forPageboyViewController pageboyViewController: PageboyViewController) -> [UIViewController]? {
	// return array of view controllers
	return [viewController1, viewController2]
}

func defaultPageIndex(forPageboyViewController pageboyViewController: PageboyViewController) -> PageboyViewController.PageIndex? {
	// use default index
	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,
                             willScrollToPageAtIndex 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,
                             didScrollToPosition position: CGPoint,
                             direction: PageboyViewController.NavigationDirection)

didScrollToPage

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

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

didReload

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

func pageboyViewController(_ pageboyViewController: PageboyViewController,
                             didReload viewControllers: [UIViewController],
                             currentIndex: PageboyViewController.PageIndex)

Additional functionality

  • 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)

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

AutoScrolling

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.

Properties

View Controller Management

  • viewControllers: [UIViewController]? - The view controllers that are displayed in the page view controller.
  • currentViewController: UIViewController? - The view controller that the page view controller is currently at.

Positional Data

  • currentIndex: Int? - The page index that the page view controller is currently at.
  • currentPosition: CGPoint? - The relative page position that the page view controller is currently at.

Interaction

  • isScrollEnabled: Bool - Whether scroll is enabled on the page view controller.
  • isDragging: Bool - Whether the page view controller is currently being dragged.
  • isScrollingAnimated: Bool - Whether the page view controller is currently animating a scroll between pages.
  • isUserInteractionEnabled: Bool - Whether user interaction is enabled on the page view controller.
  • navigationOrientation: UIPageViewControllerNavigationOrientation - The orientation that the page view controller transitions on.
  • isInfiniteScrollEnabled: Bool - Whether the page view controller should infinitely scroll between page limits (i.e. able to continuously scroll to first page from last).

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.