Swiftpack.co - Package - uias/Pageboy

Pageboy

CocoaPods Platforms

TL;DR UIPageViewController done properly.

⭐️ Features

  • ☑ Simplified data source management & enhanced delgation.
  • ☑ Dynamically insert & remove pages.
  • ☑ Infinite scrolling support.
  • ☑ Automatic timer-based page transitioning.
  • ☑ Support for custom animated page transitions.

📋 Requirements

Pageboy requires iOS 9 / tvOS 10; and is compatible with Swift 4/5.

📲 Installation

CocoaPods

Pageboy is available through CocoaPods:

pod 'Pageboy', '~> 3.2'

Carthage

Pageboy is also available through Carthage:

github "uias/Pageboy" ~> 3.2

🚀 Usage

The Basics

  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
}

PageboyViewControllerDelegate

The delegate functions provided by a PageboyViewController are much more reliable and useful than what a raw UIPageViewController provides. You can use them to find out exactly where the current page is, and when it's moved, where it's headed.

willScrollToPageAtIndex

About to embark on a transition to a new page.

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

didScrollToPosition

Scrolled to a relative position along the way transitioning to a new page.

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

didScrollToPage

Successfully completed a scroll transition to a page.

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

didReload

Child view controllers have been reloaded.

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

Navigation

You can navigate programmatically through a PageboyViewController using scrollToPage():

pageViewController.scrollToPage(.next, animated: true)
  • Infinite scrolling can be enabled with .isInfiniteScrollEnabled.
  • Interactive scrolling can also be controlled with .isScrollEnabled.

Insertion & Deletion

Pageboy provides the ability to insert and delete pages dynamically in the PageboyViewController.

func insertPage(at index: PageIndex, then updateBehavior: PageUpdateBehavior)
func deletePage(at index: PageIndex, then updateBehavior: PageUpdateBehavior)

This behaves similarly to the insertion of rows in UITableView, in the fact that you have to update the data source prior to calling any of the update functions.

Example:

let index = 2
viewControllers.insert(UIViewController(), at: index)
pageViewController.insertPage(at: index)

The default behaviour after inserting or deleting a page is to scroll to the update location, this however can be configured by passing a PageUpdateBehavior value other than .scrollToUpdate.

⚡️ Other Extras

  • reloadData() - Reload the view controllers in the page view controller. (Reloads the data source).
  • .navigationOrientation - Whether to orientate the pages horizontally or vertically.
  • .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.
  • .parentPageboy - Access the immediate parent PageboyViewController from any child view controller.

Animated Transitions

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

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

Note: By default this is set to nil, which uses the standard animation provided by UIPageViewController.

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.

Github

link
Stars: 1424

Dependencies

Used By

Total: 0

Releases

3.5.1 - 2020-03-16 09:00:52

Fixed

  • Mixed language errors caused by Pageboy.h header in Swift PM.

3.5.0 - 2019-10-06 08:37:08

Added

  • #230 didCancelScrollToPage function to PageboyViewControllerDelegate for detecting page transitions that were cancelled.

Fixed

  • #227 UIPageViewController bug that causes the page view controller to display the wrong page (see here).

3.4.0 - 2019-08-25 13:41:36

Updated

  • Add support for Swift Package Manager in Xcode 11.

3.3.0 - 2019-08-05 08:57:53

Added

Fixed

  • Issues with building on tvOS.
  • Broken imports when building with Carthage.

3.2.3 - 2019-06-10 16:36:12

Updated

  • Added support for multiple Swift versions to podspec.

3.2.2 - 2019-05-04 13:45:24

Fixed

  • #209 Issue where pages could not be added when no pages exist.
  • #208 Issue where the last page could not be deleted.

3.2.1 - 2019-04-24 07:59:37

Fixed

  • Warnings related to Objective-C enums.
  • SwiftLint warnings.
  • Incorrect Swift version in Podspec, now 4.0.

3.2.0 - 2019-03-26 20:19:41

Added

  • Swift 5 support.
  • Xcode 10.2 support.

3.1.0 - 2019-03-08 12:05:52

Added

  • pageboyParent to UIViewController to get the parent PageboyViewController if it exists.
  • pageboyPageIndex to UIViewController to get the current index of a view controller if embedded within a PageboyViewController.

Updated

  • Deprecated parentPageboy on UIViewController.

3.0.7 - 2019-03-03 10:20:01

Fixed

  • #202 Issue where page index map could crash with invalid keys (Relates to #198).

3.0.6 - 2019-03-03 08:26:16

Fixed

  • #198 Memory issue where view controllers would always be retained.

3.0.5 - 2019-02-22 10:24:45

Updated

  • #196 Improved extension access controls.

3.0.4 - 2019-02-17 09:59:58

Fixed

  • #195 Ensure view controller update work is performed synchronously on the main thread.

3.0.3 - 2019-02-13 18:55:14

Updated

3.0.2 - 2019-02-10 18:45:50

Fixed

  • #192 Thread safety improvements to resolve UIPageViewController crashes.

3.0.1 - 2018-12-01 12:39:59

Fixed

  • #187 Issue where using unowned self could cause memory crashes.
  • #176 Issue where checking UI layout direction could cause threading issues.

Pageboy 3 - 2018-11-13 19:51:57

Added

  • Support for dynamically inserting a new page via insertPage(at: PageIndex).
  • Support for dynamically deleting an existing page via deletePage(at: PageIndex).
  • Improved support for Swift 4 and 4.2.

Updated

  • Status bar style update animation when changing pages now lasts 0.25 seconds.
  • Improved Example app with support for in-app Settings.
  • Auto-Scrolling will now automatically resume/pause with viewDidAppear/viewWillDisappear lifecycle events.

Fixed

  • Numerous memory leaks and performance problems.

Upgrade Notes

This release and any following v3.0 releases will include API breaking changes from any previous 2.x release. When upgrading to v3.0 from a v2.x install, please read the accompanying migration notes that can be found here: Pageboy 3 Migration Guide.

Pageboy 3 - Beta 3 - 2018-10-18 18:20:06

Upgrade Notes

This beta release and any following v3.0 releases will include API breaking changes from any previous 2.x release. When upgrading to v3.0 from a v2.x install, please read the accompanying migration notes that can be found here: Pageboy 3 Migration Guide.

2.6.1 - 2018-10-01 07:43:12

Fixed

  • #175 Issue where expectedTransitionIndex could be incorrect when cancelling scroll events.

2.6.0 - 2018-09-16 16:43:41

Updated

  • Migrated to use Swift 4.2.

Pageboy 3 - Beta 2 - 2018-08-02 11:41:20

Upgrade Notes

This beta release and any following v3.0 releases will include API breaking changes from any previous 2.x release. When upgrading to v3.0 from a v2.x install, please read the accompanying migration notes that can be found here: Pageboy 3 Migration Guide.

Pageboy 3 - Beta 1 - 2018-07-31 14:15:19

Upgrade Notes

This beta release and any following v3.0 releases will include API breaking changes from any previous 2.x release. When upgrading to v3.0 from a v2.x install, please read the accompanying migration notes that can be found here: Pageboy 3 Migration Guide.

2.5.4 - 2018-07-19 09:33:13

Fixed

  • #166 Issue where view controllers would fail to update correctly when transitions were interrupted.

2.5.3 - 2018-07-18 13:52:53

Fixed

  • #166 Interaction and state issues when transitions were interrupted.

2.5.2 - 2018-06-28 11:55:53

Fixed

  • #165 Animated transition issues when using a Right-to-left language.

2.5.1 - 2018-04-23 20:31:53

Fixed

  • #159 Current Index is negative when infinite scroll is enabled and scrolling between ranges.

2.5.0 - 2018-04-05 20:18:43

Updated

  • parentPageboyViewController has been renamed to parentPageboy.

Fixed

  • #157 Fix scroll detection edge case when decelerating on page index.

2.4.0 - 2018-02-23 14:58:15

Updated

  • #136 Add support for default UIPageViewController animated transition.
  • #136 Obseleted default Transition.
  • Mark showsPageControl as unavailable rather than deprecated.

2.3.4 - 2018-02-12 20:36:36

Fixed

  • #140 Potential crash when scrolling through pages with high velocity.

2.3.3 - 2018-01-30 14:36:49

Fixed

  • Build issues when trying to integrate with Carthage.