PagedMediaViewer

Features

PagedMediaViewer is an elegant media display library, comparable to native Photos app, supporting both images and videos.

• [x] Smooth thumbnail-to-fullscreen interactive transition with return animation
• [x] Fullscreen display of any custom (media) view conforming to PagedMediaItem protocol
• [x] Configurable header, footer, and playback controls
• [x] Double tap & pinch to zoom with auto-hiding UI elements
• [x] Adjustable presentation insets to allow underlying views to remain visible (e.g. promotional content)
• [x] Comprehensive Unit & UI Test Coverage
• [x] Complete Documentation

Demo

Image transition	Video transition & zoom	Media items pagination

The previews are from the example project. To run the example project, clone the repo, and run pod install from the Example directory first.

Usage

Quick Start

Check PagedMediaViewControllerExample.swift PagedMediaDataSource and PagedMediaDelegate implementation from the Example project.

PagedMediaItem protocol

Media item to be presented in the PagedMediaViewController.

public protocol PagedMediaItem: UIView {
    /// Updates paused state depending on the transition status.
    var paused: Bool { get set }
    /// Whether the item is animated (video, gif, etc) or static (image, etc).
    var isAnimated: Bool { get }
    /// Used in the last part of the dismissal transition for animated items (if not `nil`) for smooth effect. Defaults to `nil`.
    var animatedItemSnapshotAtCurrentTime: UIImage? { get }
    /// Controls for play/pause and scrubbing.  Defaults to `nil`.
    var animatedItemControlsView: UIView? { get }
}

PagedMediaDataSource protocol

Conform to PagedMediaDataSource to provide media items and customize their presentation.

public protocol PagedMediaDataSource: AnyObject {
    /// Number of items to be presented.
    func numberOfItems(in pagedMediaViewController: PagedMediaViewController) -> Int
    /// Adds insets  on `PagedMediaViewController`'s view presentation frame. Defaults to `.zero`. Useful for preventing presentation over promotional content.
    func presentationViewInsets(for pagedMediaViewController: PagedMediaViewController) -> UIEdgeInsets
    /// Provides the media item view for the given index.
    func pagedMediaViewController(_ pagedMediaViewController: PagedMediaViewController, pagedMediaViewForItemAt index: Int) -> PagedMediaItem
    /// Provides the original view for the given index. Used for transition animations.
    func pagedMediaViewController(_ pagedMediaViewController: PagedMediaViewController, originalViewForItemAt index: Int) -> UIView
    /// Optional method for specifying the original image for the view or a snapshot. By default `PagedMediaTransitionDriver` will create a snapshot from the original view.
    func pagedMediaViewController(_ pagedMediaViewController: PagedMediaViewController, transitionImageForItemAt index: Int) -> UIImage?
}

PagedMediaDelegate protocol

Optional: Conform to PagedMediaDelegate for transition and item change events.

public protocol PagedMediaDelegate: AnyObject {
    /// Called just before the transition to a new item begins. Useful for centering table/collection view items behind the scenes for proper transition animation.
    func pagedMediaViewController(_ pagedMediaViewController: PagedMediaViewController, willTransitionTo index: Int)
    /// Called after the transition to a new item is completed.
    func pagedMediaViewController(_ pagedMediaViewController: PagedMediaViewController, didTransitionTo toIndex: Int, fromIndex: Int)
    /// Called just before the transition ends. Perfect time to unpause the original view at index.
    func pagedMediaViewController(_ pagedMediaViewController: PagedMediaViewController,
                                     willDismissToOriginalViewAt index: Int,
                                     fromPagedMediaItem mediaItem: PagedMediaItem)
}

Requirements

• iOS 13.0+
• Xcode 13.0+
• Swift 5.5+

Installation

CocoaPods

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

$ gem install cocoapods

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

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '13.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'PagedMediaViewer'
end

Then, run the following command:

$ pod install

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.

Once you have your Swift package set up, adding PagedMediaViewer as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
    .package(url: "https://github.com/sukov/PagedMediaViewer.git", .upToNextMajor(from: "1.0.3"))
]

Author

sukov, gorjan.shukov@gmail.com

License

PagedMediaViewer is available under the MIT license. See the LICENSE file for more info.