Swiftpack.co - Package - JanGorman/Agrume

Agrume

Build Status Carthage compatible Version License Platform SPM

An iOS image viewer written in Swift with support for multiple images.

Agrume

Requirements

  • Swift 5.0
  • iOS 9.0+
  • Xcode 10.2+

Installation

Use Swift Package Manager.

Or CocoaPods. Add the dependency to your Podfile and then run pod install:

pod "Agrume"

Or Carthage. Add the dependency to your Cartfile and then run carthage update:

github "JanGorman/Agrume"

Usage

There are multiple ways you can use the image viewer (and the included sample project shows them all).

For just a single image it's as easy as

Basic

import Agrume

@IBAction func openImage(_ sender: Any) {
  let agrume = Agrume(image: UIImage(named: "…")!)
  agrume.show(from: self)
}

You can also pass in a URL and Agrume will take care of the download for you.

Background Configuration

Agrume has different background configurations. You can have it blur the view it's covering or supply a background color:

let agrume = Agrume(image: UIImage(named: "…")!, background: .blurred(.regular))
// or
let agrume = Agrume(image: UIImage(named: "…")!, background: .colored(.green))

Multiple Images

If you're displaying a UICollectionView and want to add support for zooming, you can also call Agrume with an array of either images or URLs.

// In case of an array of [UIImage]:
let agrume = Agrume(images: images, startIndex: indexPath.item, background: .blurred(.light))
// Or an array of [URL]:
// let agrume = Agrume(urls: urls, startIndex: indexPath.item, background: .blurred(.light))

agrume.didScroll = { [unowned self] index in
  self.collectionView.scrollToItem(at: IndexPath(item: index, section: 0), at: [], animated: false)
}
agrume.show(from: self)

This shows a way of keeping the zoomed library and the one in the background synced.

Animated gifs

Agrume bundles SwiftyGif to display animated gifs. You use SwiftyGif's custom UIImage initializer:

let image = UIImage(gifName: "animated.gif")
let agrume = Agrume(image: image)
agrume.display(from: self)

// Or gif using data:

let image = UIImage(gifData: data)
let agrume = Agrume(image: image)

// Or multiple images:

let images = [UIImage(gifName: "animated.gif"), UIImage(named: "foo.png")] // You can pass both animated and regular images at the same time
let agrume = Agrume(images: images)

Remote animated gifs (i.e. using the url or urls initializer) are supported. Agrume does the image type detection and displays them properly. If using Agrume from a custom UIImageView you may need to rebuild the UIImage using the original data to preserve animation vs. using the UIImage instance from the image view.

Close Button

Per default you dismiss the zoomed view by dragging/flicking the image off screen. You can opt out of this behaviour and instead display a close button. To match the look and feel of your app you can pass in a custom UIBarButtonItem:

// Default button that displays NSLocalizedString("Close", …)
let agrume = Agrume(image: UIImage(named: "…")!, .dismissal: .withButton(nil))
// Customise the button any way you like. For example display a system "x" button
let button = UIBarButtonItem(barButtonSystemItem: .stop, target: nil, action: nil)
button.tintColor = .red
let agrume = Agrume(image: UIImage(named: "…")!, .dismissal: .withButton(button))

The included sample app shows both cases for reference.

Custom Download Handler

If you want to take control of downloading images (e.g. for caching), you can also set a download closure that calls back to Agrume to set the image. For example, let's use MapleBacon.

import Agrume
import MapleBacon

@IBAction func openURL(_ sender: Any) {
  let agrume = Agrume(url: URL(string: "https://dl.dropboxusercontent.com/u/512759/MapleBacon.png")!)
  agrume.download = { url, completion in
    Downloader.default.download(url) { image in
      completion(image)
    }
  }
  agrume.show(from: self)
}

Global Custom Download Handler

Instead of having to define a handler on a per instance basis you can instead set a handler on the AgrumeServiceLocator. Agrume will use this handler for all downloads unless overriden on an instance as described above:

import Agrume

AgrumeServiceLocator.shared.setDownloadHandler { url, completion in
  // Download data, cache it and call the completion with the resulting UIImage
}

// Some other place
agrume.show(from: self)

Custom Data Source

For more dynamic library needs you can implement the AgrumeDataSource protocol that supplies images to Agrume. Agrume will query the data source for the number of images and if that number changes, reload it's scrolling image view.

import Agrume

let dataSource: AgrumeDataSource = MyDataSourceImplementation()
let agrume = Agrume(dataSource: dataSource)

agrume.show(from: self)

Status Bar Appearance

You can customize the status bar appearance when displaying the zoomed in view. Agrume has a statusBarStyle property:

let agrume = Agrume(image: image)
agrume.statusBarStyle = .lightContent
agrume.show(from: self)

Long Press Gesture and Downloading Images

If you want to handle long press gestures on the images, there is an optional onLongPress closure. This will pass an optional UIImage and a reference to the Agrume UIViewController as parameters. The project includes a helper class to easily opt into downloading the image to the user's photo library called AgrumePhotoLibraryHelper. First, create an instance of the helper:

private func makeHelper() -> AgrumePhotoLibraryHelper {
  let saveButtonTitle = NSLocalizedString("Save Photo", comment: "Save Photo")
  let cancelButtonTitle = NSLocalizedString("Cancel", comment: "Cancel")
  let helper = AgrumePhotoLibraryHelper(saveButtonTitle: saveButtonTitle, cancelButtonTitle: cancelButtonTitle) { error in
    guard error == nil else {
      print("Could not save your photo")
      return
    }
    print("Photo has been saved to your library")
  }
  return helper
}

and then pass this helper's long press handler to Agrume as follows:

let helper = makeHelper()
agrume.onLongPress = helper.makeSaveToLibraryLongPressGesture

Custom Overlay View

You can customise the look and functionality of the image views. To do so, you need create a class that inherits from AgrumeOverlayView: UIView. As this is nothing more than a regular UIView you can do anything you want with it like add a custom toolbar or buttons to it. The example app shows a detailed example of how this can be achieved.

Lifecycle

Agrume offers the following lifecycle closures that you can optionally set:

  • willDismiss
  • didDismiss
  • didScroll

Running the Sample Code

The project ships with an example app that shows the different functions documented above. Since there is a dependency on SwiftyGif you will also need to fetch that to run the project. It's included as git submodule. After fetching the repository, from the project's root directory run:

git submodule update --init

Licence

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

Github

link
Stars: 409

Dependencies

Used By

Total: 0

Releases

- 2020-08-22 07:13:48

  • Fix left alignment of cells in Mac Catalyst. Thanks @hyouuu for the contribution

- 2020-04-19 13:39:02

  • Fix #182 RTL display issue

- 2020-03-23 13:14:06

  • Use the instance DownloadHandler. Thanks @najeeb-ur-rehman for the fix

- 2020-03-22 06:30:51

  • Removes test target from Package.swift. Thanks @sschizas

- 2020-02-18 09:48:09

  • Expose the background property publicly. Thanks @chih98 for the PR

- 2020-02-06 09:46:36

- 2020-02-06 06:16:00

  • Add support for Swift Package Manager. Thanks @sschizas for the addition.

- 2020-01-29 08:33:52

  • Fixes crash when using a custom data source. Thanks @ryan-w for reporting.

- 2020-01-26 14:36:53

  • Fix layout issue with landscape images. Thanks @hyouuu

- 2020-01-14 18:55:46

  • Remove static blurred snapshot, instead blur the view controller behind the gallery directly

- 2020-01-13 12:31:52

  • Add a helper to download images on long press. Thanks @Alexookah

- 2020-01-12 15:50:06

  • Support for custom overlay views. Thanks @ryan-w 🎉

- 2020-01-03 09:42:26

  • Support for iPad Multitasking. Thanks @Alexookah

- 2019-12-31 08:29:50

  • Adds a long press gesture
  • Update image or image URL at index

Thanks @hyouuu

- 2019-12-30 14:48:51

  • Revert changes made with release 5.3.10

- 2019-12-27 13:14:37

  • Support for iPad Multitasking. Thanks @Alexookah

- 2019-12-20 10:40:29

  • Adds a willDismiss block. Thanks @hyouuu

- 2019-12-17 06:14:51

  • Fix for close button position on iOS 10. See #142

- 2019-12-13 15:58:54

  • Fixes issue with gif images (See #140)

- 2019-12-10 06:20:45

  • Fix recentering images. Thanks @Alexookah

- 2019-12-06 06:20:44

  • Improving didScroll when Swiping Left & Right. Thanks @Alexookah

- 2019-11-26 06:22:54

  • Handling safe area insets
  • Graceful rotation

Thanks to @Alexookah for all the fixes 🎉

- 2019-11-25 12:39:38

  • Make Agrume's navigation bar transparent by default. Thanks @Alexookah

- 2019-08-29 11:24:29

  • Fix blurContainerView's size, it was hidden #120 Thanks @matteinn for the fix.

- 2019-04-15 05:15:42

  • Push SwiftyGif update. Thanks @anilgoktas

Swift 5 - 2019-04-02 11:29:02

  • Update to Swift 5

didScroll fix - 2019-02-23 16:49:52

  • The call to the didScroll closure went missing with the V 5 release. It's back.

- 2018-12-05 20:22:32

  • Adds support for a third dismiss configuration that combines physics and a button

Improved Carthage support - 2018-10-23 10:06:10

Thanks @LeeroyDing for the PR.

Fix gif playback - 2018-10-19 10:58:59

  • Use SwiftyGif again. Now properly supports Swift 4.2