An easy to use drop-in framework providing user interface for taking pictures and videos and pick assets from Photo Library. User interface is designed to support inputView
"keyboard-like" presentation for conversation user interfaces. Project is written in Swift4.
Features:
Requirements
Installation
A central object ImagePickerController
manages user interactions and delivers the results of those interactions to a delegate object. The role and appearance of an image picker controller depend on the configuration you set up before presenting it.
Image Picker consists of 3 main functional parts:
To use an image picker controller, you must provide a delegate that conforms to ImagePickerControllerDelegate
protocol. Use delegate to get informed when user takes a picture or selects an asset from library and configure custom action and asset collection view cells.
To use an image picker controller, perform these steps:
info.plist
file (see Permissions section for more info.)iOS requires you to register the following permission keys in info.plist:
NSPhotoLibraryUsageDescription
- for displaying photos and videos from device's Photo LibraryNSCameraUsageDescription
- for taking pictures and capturing videosNSMicrophoneUsageDescription
- for recording videos or live photos with an audio trackApp asks for permissions automatically only when it's needed.
Various kind of configuration is supported. All configuration should be done before the view controller's view is first accessed.
CaptureSettings
Appearance
classLayoutConfiguration
class.CellRegistrator
classdelegate
and dataSource
if neededassetsFetchResultBlock
blockCurrently Image Picker supports capturing photos, live photos and videos.
To configure Image Picker to support desired media type use CaptureSettings
struct. Use property cameraMode
to specify what kind of output you are interested in. If you don't intend to support live photos at all, please use value photo
, otherwise photoAndLivePhoto
. If you wish to capture photos and videos use photoAndVideo
. Capturing videos and live photos at the same time is not supported and you nor can't switch between presets after it's been configrued.
By default, all captured photos are not saved to Photo Library but rather provided to you by the delegate right away. However if you wish to save photos to photo library set savesCapturedPhotosToPhotoLibrary
to true. Live photos and videos are saved to Photo Library automatically.
An example of configuration for taking photos and live photos and saving them to photo library:
let imagePicker = ImagePickerController()
imagePicker.captureSettings.cameraMode = .photoAndLivePhoto
imagePicker.captureSettings.savesCapturedPhotosToPhotoLibrary = true
Please refer to CaptureSettings
public header for more information.
By default Image Picker fetches from Photo Library 1000 photos and videos from smart album smartAlbumUserLibrary
that should represent Camera Roll album. If you wish to provide your own fetch result please implement image picker controller's assetsFetchResultBlock
block.
For example to fetch only live photos you can use following code snippet:
let imagePicker = ImagePickerController()
imagePicker.assetsFetchResultBlock = {
guard let livePhotosCollection = PHAssetCollection.fetchAssetCollections(with: .smartAlbum, subtype: .smartAlbumLivePhotos, options: nil).firstObject else {
return nil //you can return nil if you did not find desired fetch result, default fetch result will be used.
}
return PHAsset.fetchAssets(in: livePhotosCollection, options: nil)
}
For more information how to configure fetch results please refer to Photos framework documentation.
Image picker view hierarchy contains of UICollectionView
to show action, camera and asset items and an overlay view to show permissions status. When custom cells are provided via CellRegistrator
it is your responsibility to do the styling as well styling custom overlay view for permissions status. However, few style attributes are supported such as background color. Please use custom appearance mechanism to achieve desired styling.
ImagePickerController.appearance().backgroundColor = UIColor.black
let vc = ImagePickerController()
vc.appearance().backgroundColor = UIColor.black
For default styling attributes and more info please refer to public interface of Appearance
class.
Please note that UIKit's appearance proxy is not currently supported.
Image picker supports various kind of layouts and both vertical and horizontal scroll direction. Using LayoutConfiguration
you can set layout that you need specifically to your app.
let imagePicker = ImagePickerController()
imagePicker.layoutConfiguration.showsSecondActionItem = false
let imagePicker = ImagePickerController()
imagePicker.layoutConfiguration.showsCameraItem = false
Please note that if you turn off camera section, Image Picker will not ask user for camera permissions.
let imagePicker = ImagePickerController()
imagePicker.layoutConfiguration.numberOfAssetItemsInRow = 1
Please note that provided value must be greater than 0 otherwise an exception will be thrown.
All views used by Image Picker can be provided by you to achieve highly customisable UI that fits your app the best. As mentioned earlier, whole UI consists of a collection view and an overlay view.
CellRegistrator
. It contains API to register both nibs and classes for each section type. For example to register custom cells for action items section use following code:let imagePicker = ImagePickerController()
imagePicker.cellRegistrator.registerNibForActionItems(UINib(nibName: "IconWithTextCell", bundle: nil))
Same principle is applied to registering custom camera and asset items. You can also set specific cells for each asset media types such photos and videos. For example to use specific cell for video assets use:
let imagePicker = ImagePickerController()
imagePicker.cellRegistrator.register(cellClass: CustomVideoCell.self, forAssetItemOf: .video)
imagePicker.cellRegistrator.register(cellClass: CustomImageCell.self, forAssetItemOf: .image)
Note: Please make sure that if you use custom cells you register cells for all media types (audio, video) otherwise Image Picker will throw an exception. Please don't forget that camera item cells must subclass CameraCollectionViewCell and asset items cells must conform to
ImagePickerAssetCell
protocol. You can also fine-tune your asset cells to a specific asset types such us live photos, panorama photos, etc. using the delegate. Please see our ExampleApp for implementation details.
ImagePickerControllerDatasource
protocol. Possible implementation could look like this:extension ViewController: ImagePickerControllerDataSource {
func imagePicker(controller: ImagePickerController, viewForAuthorizationStatus status: PHAuthorizationStatus) -> UIView {
let statusView = CustomPermissionStatusView(frame: .zero)
//configure and return view based on authorization status
return statusView
}
}
If you wish to use your own action item cells, please register your cell classes or nibs at CellRegistrator
. After that implement corresponding ImagePickerControllerDelegate
method to configure cell before it's displayed.
let imagePicker = ImagePickerController()
imagePicker.layoutConfiguration.showsFirstActionItem = true
imagePicker.layoutConfiguration.showsSecondActionItem = true
imagePicker.registerCellClassForActionItems(IconWithTextCell.self)
func imagePicker(controller: ImagePickerController, willDisplayActionItem cell: UICollectionViewCell, at index: Int) {
switch cell {
case let iconWithTextCell as IconWithTextCell:
switch index {
case 0:
iconWithTextCell.titleLabel.text = "Camera"
iconWithTextCell.imageView.image = #imageLiteral(resourceName: "ic-camera")
case 1:
iconWithTextCell.titleLabel.text = "Photo Library"
iconWithTextCell.imageView.image = #imageLiteral(resourceName: "ic-photo")
default: break
}
default:
break
}
}
func imagePicker(controller: ImagePickerController, didSelectActionItemAt index: Int) {
print("did select action \(index)")
}
Image picker provides a default camera cell that adapts to taking pictures, live photos or videos based on captureSettings
.
If you wish to implement fancier features you must provide your own subclass of CameraCollectionViewCell
or nib file with custom cell class subclassing it and implement dedicated methods.
Note: Please note, that custom nib's cell class must inherit from
CameraCollectionViewCell
and must not specify any reuse identifer. Image Picker is handling reuse identifiers internally.
Supported features of whoose UI can be fully customized:
To see an example of custom implementation that supports all mentioned features please see class LivePhotoCameraCell
and VideoCameraCell
of Image Picker source code..
Image picker provides a default assets cell that shows an image thumbnail, selected state, if asset is video it shows an icon and duration and if it's an live photo it shows an icon. If you wish to provide custom asset cell, that could show for example asset's media subtype (live photo, panorama, HDR, screenshot, streamed video, etc.) simply register your own asset cells on CellRegistrator
that conforms to ImagePickerAssetCell
and in implement image picker delegate's func imagePicker(controller: ImagePickerController, willDisplayAssetItem cell: ImagePickerAssetCell, asset: PHAsset)
method. Possible example implementation could be:
let imagePicker = ImagePickerController()
imagePicker.register(cellClass: CustomImageCell.self, forAssetItemOf: .image)
imagePicker.register(cellClass: CustomVideoCell.self, forAssetItemOf: .video)
Please note, that
CellRegistrator
provides a method to register 1 cell or nib for any asset media type.
func imagePicker(controller: ImagePickerController, willDisplayAssetItem cell: ImagePickerAssetCell, asset: PHAsset) {
switch cell {
case let videoCell as CustomVideoCell:
videoCell.label.text = ViewController.durationFormatter.string(from: asset.duration)
case let imageCell as CustomImageCell:
if asset.mediaSubtypes.contains(.photoLive) {
imageCell.subtypeImageView.image = #imageLiteral(resourceName: "icon-live")
}
else if asset.mediaSubtypes.contains(.photoPanorama) {
imageCell.subtypeImageView.image = #imageLiteral(resourceName: "icon-pano")
}
else if #available(iOS 10.2, *), asset.mediaSubtypes.contains(.photoDepthEffect) {
imageCell.subtypeImageView.image = #imageLiteral(resourceName: "icon-depth")
}
default:
break
}
}
To see an example of custom implementation that supports all mentioned features please see class VideoAssetCell
and AssetCell
of Image Picker source code.
If you wish to present Image Picker in default set up, you don't need to do any special configuration, simple create new instance and present a view controller:
let imagePicker = ImagePickerController()
navigationController.present(imagePicker, animated: true, completion: nil)
However, most of the time you will want to do custom configuration so please do all the configuration before the view controller's view is loaded (viewDidLoad()
method is called).
let imagePicker = ImagePickerController()
imagePicker.cellRegistrator ...
imagePicker.layoutConfiguration ...
imagePicker.captureSettings ...
imagePicker.appearance...
imagePicker.dataSource = ...
imagePicker.delegate = ...
navigationController.present(imagePicker, animated: true, completion: nil)
If you wish to present Image Picker as "keyboard" in your chat app, you have to set view controller's view as inputView of your first responder and:
.flexibleHeight
if view's height should be default keyboard heightframe.size.height
to get fixed heightOptionaly, before presenting image picker, you can check if user has granted access permissions to Photos Library using PHPhotoLibrary
API and ask for permissions. If you don't do it, image picker will take care of this automatically for you after it's presented.
All user actions such as selecting/deselecting of assets, taking new photos or livephotos or capturing vides are advertised using ImagePickerControllerDelegate
delegate methods. For list and more detail explanation please see public header.
Sometimes you will need to manage selected assets programatically. Image Picker provides several convinience methods to work with asset items.
selectedAssets
property returns an array of currently selected PHAsset
itemsassets(at:)
and asset(at:)
selectAsset(at:animated:scrollPosition:)
deselectAsset(at:animated:)
deselectAllAssets(_:)