πΌ ImageSlideshow
Customizable Swift image slideshow with circular scrolling, timer and full screen viewer
π± Example
To run the example project, clone the repo, and run pod install
from the Example directory first.
π§ Installation
CocoaPods
ImageSlideshow is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'ImageSlideshow', '~> 1.9.0'
Carthage
To integrate ImageSlideshow into your Xcode project using Carthage, specify it in your Cartfile:
github "zvonicek/ImageSlideshow" ~> 1.9.0
Carthage does not include InputSources for external providers (due to dependency on those providers) so you need to grab the one you need from ImageSlideshow/Classes/InputSources
manually.
Manually
One possibility is to download a built framework (ImageSlideshow.framework.zip) from releases page and link it with your project (underLinked Frameworks and Libraries
in your target). This is, however, currently problematic because of rapid Swift development -- the framework is built for a single Swift version and may not work on previous/future versions.
Alternatively can also grab the whole ImageSlideshow
directory and copy it to your project. Be sure to remove those external Input Sources you don't need.
Note on Swift 2.3, Swift 3 and Swift 4 support
Version 1.4 supports Swift 4. Swift 3 is supported from version 1.0, for Swift 2.2 and Swift 2.3 compatible code use version 0.6 or branch swift-2.3.
π¨ How to use
Add ImageSlideshow view to your view hiearchy either in Interface Builder or in code.
Loading images
Set images by using setImageInputs
method on ImageSlideshow
instance with an array of InputSources. By default you can use ImageSource
which takes UIImage
or few other InputSources for most popular networking libraries. You can also create your own input source by implementing InputSource
protocol.
Library | InputSource name | Pod |
---|---|---|
AlamofireImage | AlamofireSource | pod "ImageSlideshow/Alamofire" |
AFNetworking | AFURLSource | pod "ImageSlideshow/AFURL" |
SDWebImage | SDWebImageSource | pod "ImageSlideshow/SDWebImage" |
Kingfisher | KingfisherSource | pod "ImageSlideshow/Kingfisher" |
Parse | ParseSource | pod "ImageSlideshow/Parse" |
slideshow.setImageInputs([
ImageSource(image: UIImage(named: "myImage"))!,
ImageSource(image: UIImage(named: "myImage2"))!,
AlamofireSource(urlString: "https://images.unsplash.com/photo-1432679963831-2dab49187847?w=1080"),
KingfisherSource(urlString: "https://images.unsplash.com/photo-1432679963831-2dab49187847?w=1080"),
ParseSource(file: PFFile(name:"image.jpg", data:data))
])
Configuration
Behaviour is configurable by those properties:
slideshowInterval
- slideshow interval in seconds (default0
β disabled)zoomEnabled
- enables zooming (defaultfalse
)circular
- enables circular scrolling (defaulttrue
)activityIndicator
β allows to set custom activity indicator, see Activity indicator sectionpageIndicator
β allows to set custom page indicator, see Page indicator section; assignnil
to hide page indicatorpageIndicatorPosition
- configures position of the page indicatorcontentScaleMode
- configures the scaling (defaultScaleAspectFit
)draggingEnabled
- enables dragging (defaulttrue
)currentPageChanged
- closure called on page changewillBeginDragging
- closure called on scrollViewWillBeginDraggingdidEndDecelerating
- closure called on scrollViewDidEndDeceleratingpreload
- image preloading configuration (defaultall
preloading, alsofixed
)
Page Indicator
Page indicator can be customized using the pageIndicator
property on ImageSlideshow. By defualt, a plain UIPageControl is used. If needed, page control can be customized:
let pageIndicator = UIPageControl()
pageIndicator.currentPageIndicatorTintColor = UIColor.lightGray
pageIndicator.pageIndicatorTintColor = UIColor.black
slideshow.pageIndicator = pageIndicator
Also, a simple label page indicator that shows pages in style "5/21" (fifth page from twenty one) is provided:
slideshow.pageIndicator = LabelPageIndicator()
You can also use your own page indicator by adopting the PageIndicatorView
protocol.
Position of the page indicator can be configured by assigning a PageIndicatorPosition
value to the pageIndicatorPosition
property on ImageSlideshow. You may specify the horizontal and vertical positioning separately.
Horizontal positioning options are: .left(padding: Int)
, .center
, .right(padding: Int)
Vertical positioning options are: .top
, .bottom
, .under
, customTop(padding: Int)
, customBottom(padding: Int)
, customUnder(padding: Int)
Example:
slideshow.pageIndicatorPosition = PageIndicatorPosition(horizontal: .left(padding: 20), vertical: .bottom)
Activity Indicator
By default activity indicator is not shown, but you can enable it by setting DefaultActivityIndicator
instance to Image Slideshow:
slideshow.activityIndicator = DefaultActivityIndicator()
You can customize style and color of the indicator:
slideshow.activityIndicator = DefaultActivityIndicator(style: .white, color: nil)
There's also an option to use your own activity indicator. You just need to implement ActivityIndicatorView
and ActivityIndicatorFactory
protocols. See ActivityIndicator.swift
for more information.
Full Screen view
There is also a possibility to open full-screen image view using attached FullScreenSlideshowViewController
. The simplest way is to call:
override func viewDidLoad() {
let gestureRecognizer = UITapGestureRecognizer(target: self, action: #selector(ViewController.didTap))
slideshow.addGestureRecognizer(gestureRecognizer)
}
func didTap() {
slideshow.presentFullScreenController(from: self)
}
FullScreenSlideshowViewController
can also be instantiated and configured manually if more advanced behavior is needed.
π€ Author
Petr ZvonΓΔek
π License
ImageSlideshow is available under the MIT license. See the LICENSE file for more info.
π References
Inspired by projects:
Github
link |
Stars: 1500 |
You may find interesting
Releases
- 2020-06-25T06:48:36
- 2020-06-21T15:05:24
1.8.3 - 2020-01-19T21:50:00
1.8.1 - 2020-01-19T21:07:27
1.8.0 - 2019-05-26T18:20:37
1.7.0 - 2019-05-26T18:20:23
1.6.1 - 2018-06-11T15:38:08
Fixes
- Fixed Carthage build (#258)
- Fixed memory issues (#255)
1.6.0 - 2018-05-27T16:06:55
New Features
- Page Indicator customization (#251)
Fixes
- Fixed animation problem on orientation change (#234)
- Fixed missing close button image in Carthage build (#247)
1.5.3 - 2018-04-17T19:30:47
Fixes
- Fixed Close broken button in Full screen controller (#242)
- Fixed retain cycle (#241, @piercifani)
1.5.2 - 2018-04-15T22:04:20
New Features
- Example project demonstrating usage of Image Slideshow with parent UIImageView
Fixes
- Fix image shift on iPhone X landscape (#200)
- Add closeButtonFrame property to Full Screen controller (#226)
- Don't trigger interactive gesture recognizer on horizontal pans, fixes single image sliding issue (#224)
- Fix interactive dismiss regression on iOS 11
1.5.1 - 2018-02-04T18:27:16
Fixed division by zero error
1.5.0 - 2018-01-21T17:56:29
New Features
- Implement image load cancelling to optimize memory usage
- Improve Kingfisher InputSource to take Options parameters
- Update page control selected page during scrolling (#204)
- Add possibility to change maximum zoom scale (#221)
Fixes
- SDWebImage dependency improvements (#205)
- Fix possible division by zero crash (#187)
- Adjust close button frame to respect SafeAreaInsets (#209)
- Fix missing placeholder on AFURLSource (#218)
- Fix incorrect currentPageChanged calls (#222)
1.4.1 - 2018-01-21T16:27:19
1.4.0 - 2018-01-21T16:27:06
1.3.2 - 2017-05-30T21:56:33
1.3.1 - 2017-05-20T18:38:14
- 2017-05-08T14:38:58
New Features
- Possibility to show activity indicator during async loading
- Hide UIPageControl when sllideshow has single item
- UIScrollViewDelegate methods are now
open
instead ofpublic
Fixes
- Fix zoom transition for when a slideshow has just a single item
- Fix issue on
zoomEnabled
change
- 2017-03-19T23:35:43
New Features
- Improved placeholder handling on all remote input sources
- Deprecated
pauseTimerIfNeeded
andunpauseTimerIfNeeded
in favour ofpauseTimer
andunpauseTimer
Fixes
- Fix memory leak caused by incorrect timer invalidation
- Partially fix an UI glitch happening when "in-call" status bar is on
1.1.0 - 2017-02-19T17:50:15
New Features
- Add
willBeginDragging
anddidEndDecelerating
callback closures (@El-Fitz) - Add Parse input source (@jaimeagudo)
Fixes
- Fix image preload issue when scrolling between edges (#115)
- Fix issue caused by disabling
circular
after setting input sources (#104) - Improve example project
- Style fixes (@dogo)
1.0.0 - 2016-12-11T13:07:08
Version 1.0 aims to improve stability and brings couple of new features. Also contains few backward complatibility breaking changes.
New Features
- New input source for Kingfisher (@feiin)
- Add
currentPageChanged
closure to notify about page change (#54) - Add possibility to lazy load and release images (#42)
- Easier way to present
FullScreenSlideshowViewController
(#72) - Documentation improvements
Fixes
- Fix the case when containing VC automatically adjusts scrollview insets (#71)
- Fix crash during transition when no images set (#74)
- Rounding error fix for page calculation (#90, @mjrehder)
- Fix for black image when using fullscreen zoom (#92, @mjrehder)
- Change page on UIPageControl page change (#80)
- iOS 10 interactive transition interruption fix (5d5f22f)
- Memory fixes
API changes
currentItemIndex
was renamed tocurrentPage
set
function fromInputSource
protocol was renamed toload
and have a new closure parameter called on image load
- 2016-10-29T19:02:45
Swift 3 support - 2016-10-29T14:59:40
Swift 2.3 support, Carthage support - 2016-09-21T22:11:27
ImageSlideshow now supports Swift 2.3 and is finally available via Carthage π
0.5.1 - 2016-08-20T17:00:15
- Support for SDWebImage
- Example project improvements
0.5.0 - 2016-06-09T20:55:39
The version 0.5 cleans up the code, adds interactive fullscreen dismiss and fixes few minor issues (thanks again, @kafejo) This version also contains several background compatibility breaks, so please keep this in mind when upgrading to it.
New Features
- Interactive dismiss transition on full screen controller
- A possibility to open full screen controller from plain UIImageView
API changes
- ImageSlideshow:
currentPage
renamed tocurrentItemIndex
- FullScreenSlideshowViewController:
initialPage
renamed toinitialPageIndex
- ZoomAnimatedTransitioning: added second parameter
slideshowController: FullScreenSlideshowViewController
to constructor
- 2016-03-29T13:47:13
- Updated for Swift 2.2
- ImageSlideshow/AFNetworking updated for AFNetworking 3.0
Bug fix - 2016-03-18T08:06:38
- Fixes issue #17, #18, #21