SwiftImageCarousel

SwiftImageCarousel is a reusable UIPageController carousel for iOS

Showing:

Popularity

Downloads/wk

0

GitHub Stars

49

Maintenance

Last Commit

4yrs ago

Contributors

4

Package

Dependencies

0

License

MIT

Categories

Readme

Travis branch codecov.io CocoaPods CocoaPods Platform CocoaPods

SwiftImageCarousel

SwiftImageCarousel is a UIPageController-based framework that implements scrolling, zooming and automatic swiping carousel in a Swift application. All it needs from you is to supply it with valid image URLs and it is good to go.

Preview

Features

  • Horizontal image swiping that can be pinched and zoomed.
  • A timer to make the horizontal image swiping automatic.
  • Asynchronous image downloading that does not block the main thread. All you have to do is provide the URLs.
  • Customizable page controls appearance (the dot colors and background) -they can be set up through delegate protocol.

Requirements

  • iOS 9.0+
  • Swift 3.0+

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ gem install cocoapods

To integrate SwiftImageCarousel into your Xcode project using CocoaPods, specify it in your Podfile:


target '<Your Target Project Name>' do
use_frameworks!

pod 'SwiftImageCarousel'
end

Alternatively:

  • Git submodule add https://github.com/Centroida/SwiftImageCarousel.git.
  • Drag the SwiftImageCarousel.xcodeproj file into your Xcode project (Xcode will ask to create a workspace file if your project does not have one already)
  • Under the main app target, open the General tab and add SwiftImageCarousel under the Embedded Binaries section
  • Build the SwiftImageCarousel as a target before you import it
  • It is ready to be imported and used

Or

  • Download directly from the github link https://github.com/Centroida/SwiftImageCarousel
  • Run your project, right click on the name of your project in the files navigator and choose "Add Files to NameOfYourProject"
  • Find SwiftImageCarousel.xcodeproj and add it
  • Under the main app target, open the General tab and add SwiftImageCarousel under the Embedded Binaries section
  • Build the SwiftImageCarousel as a target before you import it
  • It is ready to be imported and used

Usage

Importing the framework

import SwiftImageCarousel

Providing the images as URLs and embedding the SwiftImageCarousel in a UIContainerViewController

    ///  A UIView declared in Main.Storyboard.
    @IBOutlet weak var containerView: UIView!

    override func viewDidLoad() {
        super.viewDidLoad()

        let storyboard = UIStoryboard (name: "Main", bundle: Bundle(for: SwiftImageCarouselVC.self))
        let vc = storyboard.instantiateInitialViewController() as! SwiftImageCarouselVC
        vc.contentImageURLs = ["<Your First URL>", "<Your Second URL>", "<Your Third URL>"]

        // Adding it to the container view
        vc.willMove(toParentViewController: self)
        containerView.addSubview(vc.view)
        vc.view.frame = CGRect(x: 0, y: 0, width: containerView.frame.width, height: containerView.frame.height)
        self.addChildViewController(vc)
        vc.didMove(toParentViewController: self)
    }

Setting up the contentImageURLs Array with image URLs provided as Strings

       let storyboard = UIStoryboard (name: "Main", bundle: Bundle(for: SwiftImageCarouselVC.self))
       let vc = storyboard.instantiateInitialViewController() as! SwiftImageCarouselVC
       
       /// Default URLs are not provided. They need to be set up.
       vc.contentImageURLs = [ "<Your First URL>", "<Your Second URL>", "<Your Third URL>"]

Setting up the noImage UIImage variable

       let storyboard = UIStoryboard (name: "Main", bundle: Bundle(for: SwiftImageCarouselVC.self))
       let vc = storyboard.instantiateInitialViewController() as! SwiftImageCarouselVC
       
       // There is no default image for this variable. It needs to be set up.
       vc.noImage = <Some UIImage from the Assets in your project>

Disabling the timer with the isTimerOn Bool variable

       let storyboard = UIStoryboard (name: "Main", bundle: Bundle(for: SwiftImageCarouselVC.self))
       let vc = storyboard.instantiateInitialViewController() as! SwiftImageCarouselVC
       
       /// Timer ON/OFF boolean variable. Timer for automatic swiping is set true(or ON) by default. If it needs to be off, it needs to be set to false.
       vc.isTimerOn = false

Changing the timer's automatic swipe interval with the swipeTimeIntervalSeconds Double variable

       let storyboard = UIStoryboard (name: "Main", bundle: Bundle(for: SwiftImageCarouselVC.self))
       let vc = storyboard.instantiateInitialViewController() as! SwiftImageCarouselVC
       
       /// The interval on which the carousel swipes automatically when timer is on. Default is 3 seconds.
       vc.swipeTimeIntervalSeconds = 1.5

Changing the SwiftImageCarouselItemVC content mode for image representation with the contentMode UIViewContentMode variable

       let storyboard = UIStoryboard (name: "Main", bundle: Bundle(for: SwiftImageCarouselVC.self))
       let vc = storyboard.instantiateInitialViewController() as! SwiftImageCarouselVC
       
       /// Enables resetting the UIViewContentMode of SwiftImageCarouselItemVC UIViewContentMode. The default is .scaleAspectFit
       vc.contentMode = .scaleToFill
       let storyboard = UIStoryboard (name: "Main", bundle: Bundle(for: SwiftImageCarouselVC.self))
       let vc = storyboard.instantiateInitialViewController() as! SwiftImageCarouselVC
       
       /// The default value of the variable is false
       vc.escapeFirstPageControlDefaultFrame = true
       let storyboard = UIStoryboard (name: "Main", bundle: Bundle(for: SwiftImageCarouselVC.self))
       let vc = storyboard.instantiateInitialViewController() as! SwiftImageCarouselVC
       
       /// Enables/disables the showing of the close button in the modal gallery
       vc.showCloseButtonInModalGallery = true

This variable would usually be used in combination with the didTapSwiftImageCarouselItemVC(SwiftImageCarouselItemController: SwiftImageCarouselItemVC) SwiftImageCarouselVCDelegate function.

       let storyboard = UIStoryboard (name: "Main", bundle: Bundle(for: SwiftImageCarouselVC.self))
       let vc = storyboard.instantiateInitialViewController() as! SwiftImageCarouselVC
       
       /// Enables/disables the showing of the modal gallery
       vc.showModalGalleryOnTap = false

Setting up the SwiftImageCarouselVCDelegate

After you create SwiftImageCarouselVC programatically, setup the swiftImageCarouselVCDelegate to self:

       let storyboard = UIStoryboard (name: "Main", bundle: Bundle(for: SwiftImageCarouselVC.self))
       let vc = storyboard.instantiateInitialViewController() as! SwiftImageCarouselVC
       vc.swiftImageCarouselVCDelegate = self

Delegate Functions Implementation after setting up the SwiftImageCarouselVCDelegate

Setting showModalGalleryOnTap to false and instead performing a different segue than the default one when clicking on one of the images in the carousel.

       /// Enables/disables the showing of the modal gallery
       vc.showModalGalleryOnTap = false 
extension ViewController: SwiftImageCarouselVCDelegate {
     func didTapSwiftImageCarouselItemVC(swiftImageCarouselItemController: SwiftImageCarouselItemVC) {
        // The user selected this swiftImageCarouselItemController
    }
}

Setting up the appearance of the page controls (colored dots)

extension ViewController: SwiftImageCarouselVCDelegate {
    func setupAppearance(forFirst firstPageControl: UIPageControl, forSecond secondPageControl: UIPageControl) {
        firstPageControl.backgroundColor = .red
        firstPageControl.currentPageIndicatorTintColor = .yellow
    }
}

Getting the timer and its properties

extension ViewController: SwiftImageCarouselVCDelegate {
    func didStartTimer(_ timer: Timer) {
        print (timer.timeInterval)
    }
}

Getting the next pageItemController when the timer is on

extension ViewController: SwiftImageCarouselVCDelegate {
     func didGetNextITemController(next pageItemController: InitialPageItemController) {
        pageItemController.view.backgroundColor = .green
    }
}

Getting the pageItemController when unwinding from ScrollablePageItemController

extension ViewController: SwiftImageCarouselVCDelegate {
     func didUnwindToPageViewController(unwindedTo pageItemController: InitialPageItemController) {
        pageItemController.view.backgroundColor = .green
    }
}

License

SwiftImageCarousel is released under the MIT license. See LICENSE for details.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100