Skip to content

Latest commit

 

History

History
260 lines (199 loc) · 11 KB

README.md

File metadata and controls

260 lines (199 loc) · 11 KB
Raw

Advanced framework for loading, caching, processing, displaying and preheating images.

Disclaimer: It's deprecated in favor of Nuke

This project has taken hundreds hours of work. If you find it useful, you can chip in for coffee to keep me going.

Alternatively, donate in ₽

Features

  • Zero config
  • Works great with both Objective-C and Swift
  • Performant, asynchronous, thread safe
Loading
Caching
Processing
  • Optional FLAnimatedImage integration
  • Optional WebP integration
  • Progressive image decoding including progressive JPEG
  • Background image decompression and scaling in a single step
  • Resize and crop loaded images to fit displayed size, add rounded corners or circle
Advanced
  • Customize different parts of the framework using dependency injection
  • Create and compose image managers into a tree of responsibility

Getting Started

  • Take a look at comprehensive demo using pod try DFImageManager command
  • Check out complete documentation and Wiki
  • Install, @import DFImageManager and enjoy!

Usage

Zero Config

[[DFImageManager imageTaskForResource:<#imageURL#> completion:^(UIImage *image, NSError *error, DFImageResponse *response, DFImageTask *task){
    // Use loaded image
}] resume];

Adding Request Options

DFMutableImageRequestOptions *options = [DFMutableImageRequestOptions new]; // builder
options.priority = DFImageRequestPriorityHigh;
options.allowsClipping = YES;

DFImageRequest *request = [DFImageRequest requestWithResource:<#imageURL#> targetSize:CGSizeMake(100, 100) contentMode:DFImageContentModeAspectFill options:options.options];

[[DFImageManager imageTaskForRequest:request completion:^(UIImage *image, NSError *error, DFImageResponse *response, DFImageTask *imageTask) {
    // Image is resized and clipped to fill 100x100px square
    if (response.isFastResponse) {
        // Image was returned synchronously from the memory cache
    }
}] resume];

Using Image Task

DFImageTask *task = [DFImageManager imageTaskForResource:<#imageURL#> completion:nil];
NSProgress *progress = task.progress;
task.priority = DFImageRequestPriorityHigh; // Change priority of executing task
[task cancel];

Using UI Components

Use methods from UIImageView category for simple cases:

UIImageView *imageView = ...;
[imageView df_setImageWithResource:<#imageURL#>];

Use DFImageView for more advanced features:

DFImageView *imageView = ...;
imageView.allowsAnimations = YES; // Animates images when the response wasn't fast enough
imageView.managesRequestPriorities = YES; // Automatically changes current request priority when image view gets added/removed from the window

[imageView prepareForReuse];
[imageView setImageWithResource:<#imageURL#>];

UICollectionView

- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath {
    UICollectionViewCell *cell = <#cell#>
    DFImageView *imageView = (id)[cell viewWithTag:15];
    if (!imageView) {
        imageView = [[DFImageView alloc] initWithFrame:cell.bounds];
        imageView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
        imageView.tag = 15;
        [cell addSubview:imageView];
    }
    [imageView prepareForReuse];
    [imageView setImageWithResource:<#image_url#>];
    return cell;
}

Cancel image task as soon as the cell goes offscreen (optional):

- (void)collectionView:(UICollectionView *)collectionView didEndDisplayingCell:(UICollectionViewCell *)cell forItemAtIndexPath:(NSIndexPath *)indexPath {
    [((DFImageView *)[cell viewWithTag:15]) prepareForReuse];
}

Preheating Images

NSArray<DFImageRequest *> *requestsForAddedItems = <#requests#>;
[DFImageManager startPreheatingImagesForRequests:requestsForAddedItems];

NSArray<DFImageRequest *> *requestsForRemovedItems = <#requests#>;
[DFImageManager stopPreheatingImagesForRequests:requestsForRemovedItems];

Progressive Image Decoding

// Enable progressive image decoding
[DFImageManagerConfiguration setAllowsProgressiveImage:YES];

// Create image request that allows progressive image
DFMutableImageRequestOptions *options = [DFMutableImageRequestOptions new];
options.allowsProgressiveImage = YES;
DFImageRequest *request = <#request#>;

DFImageTask *task = <#task#>;
task.progressiveImageHandler = ^(UIImage *__nonnull image){
    imageView.image = image;
};
[task resume];

Customizing Image Manager

id<DFImageFetching> fetcher = <#fetcher#>;
id<DFImageDecoding> decoder = <#decoder#>;
id<DFImageProcessing> processor = <#processor#>;
id<DFImageCaching> cache = <#cache#>;

DFImageManagerConfiguration *configuration = [[DFImageManagerConfiguration alloc] initWithFetcher:fetcher];
configuration.decoder = decoder;
configuration.processor = processor;
configuration.cache = cache;

[DFImageManager setSharedManager:[[DFImageManager alloc] initWithConfiguration:configuration]];

Composing Image Managers

The DFCompositeImageManager constructs a tree of responsibility from image managers and dynamically dispatch requests between them. Each manager should conform to DFImageManaging protocol. The DFCompositeImageManager also conforms to DFImageManaging protocol so that individual managers and compositions can be treated uniformly.

id<DFImageManaging> manager1 = <#manager#>
id<DFImageManaging> manager2 = <#manager#>
id<DFImageManaging> composite = [[DFCompositeImageManager alloc] initWithImageManagers:@[manager1, manager2]];

Design

Protocol Description
DFImageManaging A high-level API for loading images
DFImageFetching Performs fetching of image data (NSData)
DFImageDecoding Converts NSData to UIImage objects
DFImageProcessing Processes decoded images
DFImageCaching Stores processed images into memory cache

Installation

CocoaPods

To install DFImageManager add a dependency in your Podfile:

pod 'DFImageManager'

By default it will install these subspecs:

  • DFImageManager/Core - DFImageManager core classes
  • DFImageManager/UI - UI components

There are four more optional subspecs:

  • DFImageManager/AFNetworking - replaces networking stack with AFNetworking
  • DFImageManager/GIF - GIF support with a FLAnimatedImage dependency
  • DFImageManager/WebP - WebP support with a libwebp dependency
  • DFImageManager/PhotosKit - Photos Framework support

To install optional subspecs include them in your Podfile:

pod 'DFImageManager'
pod 'DFImageManager/AFNetworking'
pod 'DFImageManager/GIF'
pod 'DFImageManager/WebP'
pod 'DFImageManager/PhotosKit'

Carthage

DFImageManager has a limited Carthage support that doesn't feature FLAnimatedImage and AFNetworking integration. To install DFImageManager add a dependency to your Cartfile:

github "kean/DFImageManager"

Requirements

  • iOS 8.0+ / watchOS 2
  • Xcode 7.0+

Supported Image Formats

  • Image formats supported by UIImage (JPEG, PNG, BMP, and more)
  • GIF (GIF subspec)
  • WebP (WebP subspec)

Contribution

  • If you need help, use Stack Overflow. (Tag 'dfimagemanager')
  • If you found a bug, and can provide steps to reproduce it, open an issue.
  • If you have a feature request, open an issue.
  • If you want to contribute, branch of the develop branch and submit a pull request.

Contacts

License

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