Overview

A network-enabled image view that consumes minimal amounts of memory.

Intelligently crops and resizes images for optimal memory use and uses threads to avoid processing images on the UI thread.

Examples

Two basic methods for setting the display size of the network image

UIImage* image; // some previously loaded image.
NINetworkImageView* imageView = [[[NINetworkImageView alloc] initWithImage:image] autorelease];
// Method #1: Use the image's frame to determine the display size for the network image.
imageView.frame = CGRectMake(0, 0, 100, 100);
[imageView setPathToNetworkImage:@"http://farm2.static.flickr.com/1165/644335254_4b8a712be5.jpg"];
// Method #2: use the method setPathToNetworkImage:forDisplaySize:
[imageView setPathToNetworkImage: @"http://farm2.static.flickr.com/1165/644335254_4b8a712be5.jpg"
                  forDisplaySize: CGSizeMake(100, 100)];

Code Breakdown

NINetworkImageView* imageView = [[[NINetworkImageView alloc] initWithImage:image] autorelease];

Initializes the network image view with a preloaded image, usually a "default" image to be displayed until the network image downloads.

imageView.frame = CGRectMake(0, 0, 100, 100);

[imageView setPathToNetworkImage:@"http://farm2.static.flickr.com/1165/644335254_4b8a712be5.jpg"];

We must take care to set the frame before requesting the network image, otherwise the image's display size will be 0,0 and the network image won't be cropped or sized to fit.

[imageView setPathToNetworkImage: @"http://farm2.static.flickr.com/1165/644335254_4b8a712be5.jpg"

forDisplaySize: CGSizeMake(100, 100)];

If you don't want to modify the frame of the image, you can alternatively specify the display size as a parameter to the setPathToNetworkImage: method.

Use a different contentMode for the network image.

UIImage* image; // some previously loaded image.
NINetworkImageView* imageView = [[[NINetworkImageView alloc] initWithImage:image] autorelease];
imageView.frame = CGRectMake(0, 0, 100, 100);
imageView.contentMode = UIViewContentModeCenter; // Centers the image in the frame.
[imageView setPathToNetworkImage: @"http://farm2.static.flickr.com/1165/644335254_4b8a712be5.jpg"
                     contentMode: UIViewContentModeScaleAspectFill];

Code Breakdown

[imageView setPathToNetworkImage: @"http://farm2.static.flickr.com/1165/644335254_4b8a712be5.jpg"

contentMode: UIViewContentModeScaleAspectFill];

This means: after the image is downloaded, crop and resize the image with an aspect fill content mode. The image returned from the thread will be cropped and sized to fit the imageView perfectly at the given 100x100 dimensions. Because imageView has a contentMode of UIViewContentModeCenter, if we were to make the image view larger the downloaded image would stay in the center of the image view and leave empty space on all sides.

Inheritance diagram for NINetworkImageView:

Tasks
Configurable Presentation Properties
UIImage *	initialImage property

BOOL	sizeForDisplay property

NINetworkImageViewScaleOptions	scaleOptions property

CGInterpolationQuality	interpolationQuality property

Configurable Properties
NIImageMemoryCache *	imageMemoryCache property

NSOperationQueue *	networkOperationQueue property

NSTimeInterval	maxAge property

Delegation
id< NINetworkImageViewDelegate >	delegate property

Creating a Network Image View
(id)	- initWithImage:

Requesting a Network Image
(void)	- setPathToNetworkImage:

(void)	- setPathToNetworkImage:forDisplaySize:

(void)	- setPathToNetworkImage:forDisplaySize:contentMode:

(void)	- setPathToNetworkImage:forDisplaySize:contentMode:cropRect:

(void)	- setPathToNetworkImage:cropRect:

(void)	- setPathToNetworkImage:contentMode:

Reusable View
(void)	- prepareForReuse

Subclassing
The following methods are provided to aid in subclassing and are not meant to be used externally.
(void)	- networkImageViewDidStartLoading

(void)	- networkImageViewDidLoadImage:

(void)	- networkImageViewDidFailWithError:

[NIOperationDelegate] State Changes
(void)	- nimbusOperationDidStart:

(void)	- nimbusOperationWillFinish:

(void)	- nimbusOperationDidFinish:

(void)	- nimbusOperationDidFail:withError:

Method Documentation

initialImage

The image being displayed while the network image is being fetched.

@property (nonatomic, strong) UIImage* initialImage;

Discussion

This is the same image passed into initWithImage: immediately after initialization. This is used when preparing this view for reuse. Changing the initial image after creating the object will only display the new image if the currently displayed image is is the initial image or nil.

The initial image is drawn only using the view's contentMode. Cropping and resizing are only performed on the image fetched from the network.

sizeForDisplay

A flag for enabling the resizing of images for display.

@property (nonatomic) BOOL sizeForDisplay;

Discussion

When enabled, the downloaded image will be resized to fit the dimensions of the image view using the image view's content mode.

When disabled, the full image is drawn as-is. This is generally much less efficient when working with large photos and will also increase the memory footprint.

If your images are pre-cropped and sized then this isn't necessary, but the network image loader is smart enough to realize this so it's in your best interest to leave this on.

By default this is YES.

scaleOptions

Options for modifying the way images are cropped when scaling.

@property (nonatomic) NINetworkImageViewScaleOptions scaleOptions;

Discussion

By default this is NINetworkImageViewScaleToFitLeavesExcessAndScaleToFillCropsExcess.

See Also: NINetworkImageViewScaleOptions

interpolationQuality

The interpolation quality to use when resizing the image.

@property (nonatomic) CGInterpolationQuality interpolationQuality;

Discussion

The default value is kCGInterpolationDefault.

imageMemoryCache

The image memory cache used by this image view to store the image in memory.

@property (nonatomic, strong) NIImageMemoryCache* imageMemoryCache;

Discussion

The image disk cache used by this image view to store the image on disk.

It may be useful to specify your own image memory cache if you have a unique memory requirement and do not want the image being placed in the global memory cache, potentially pushing out other images.

By default this is [Nimbus imageMemoryCache].

Attention: Setting this to nil will disable the memory cache. This will force the image view to load the image from the disk cache or network, depending on what is available.

Remarks: If you replace Nimbus' global image memory cache with a new image cache after creating this image view, this image view will still use the old image cache.

See Also: Nimbus::globalImageMemoryCache; Nimbus::setGlobalImageMemoryCache:

After the image has finished downloading we store it in a disk cache to avoid hitting the network again if we want to load the image later on.

By default this is [ASIDownloadCache sharedCache].

Attention: Setting this to nil will disable the disk cache. Images downloaded from the network will be stored in the memory cache, if available.

networkOperationQueue

The network operation queue used by this image view to load the image from network and disk.

@property (nonatomic, strong) NSOperationQueue* networkOperationQueue;

Discussion

By default this is [Nimbus networkOperationQueue].

Attention: This property must be non-nil. If you attempt to set it to nil, a debug assertion will fire and Nimbus' global network operation queue will be set.

See Also: Nimbus::globalNetworkOperationQueue; Nimbus::setGlobalNetworkOperationQueue:

maxAge

The maximum amount of time that an image will stay in memory after the request completes.

@property (nonatomic) NSTimeInterval maxAge;

Discussion

If this value is non-zero then the respone header's expiration date information will be ignored in favor of using this value.

If this value is zero then the response header's max-age value will be used if it exists, otherwise it will use the Expires value if it exists.

A negative value will cause this image to NOT be stored in the memory cache.

By default this is 0.

delegate

Delegate for state change notifications.

@property (nonatomic, weak) id<NINetworkImageViewDelegate> delegate;

initWithImage:

Designated initializer.

- (id)initWithImage:(UIImage *)image;

Discussion

Parameters

image This will be the initialImage.

setPathToNetworkImage:

Load an image from the network using the current frame as the display size.

- (void)setPathToNetworkImage:(NSString *)pathToNetworkImage;

Discussion

Loads the image from the memory cache if possible, otherwise fires off a network request with this object's network image information.

Uses self.contentMode to crop and resize the image.

The image's current frame will be used as the display size for the image.

Parameters

pathToNetworkImage The network path to the image to be displayed.

setPathToNetworkImage:forDisplaySize:

Load an image from the network with a specific display size.

- (void)setPathToNetworkImage:(NSString *)pathToNetworkImage forDisplaySize:(CGSize)displaySize;

Discussion

Loads the image from the memory cache if possible, otherwise fires off a network request with this object's network image information.

Uses self.contentMode to crop and resize the image.

Parameters

pathToNetworkImage	The network path to the image to be displayed.
displaySize	Used instead of the image's frame to determine the display size.

setPathToNetworkImage:forDisplaySize:contentMode:

Load an image from the network with a specific display size.

- (void)setPathToNetworkImage:(NSString *)pathToNetworkImage forDisplaySize:(CGSize)displaySize contentMode:(UIViewContentMode)contentMode;

Discussion

Loads the image from the memory cache if possible, otherwise fires off a network request with this object's network image information.

Parameters

pathToNetworkImage	The network path to the image to be displayed.
displaySize	Used instead of the image's frame to determine the display size.
contentMode	The content mode used to crop and resize the image.

setPathToNetworkImage:forDisplaySize:contentMode:cropRect:

Load an image from the network with a specific display size and crop rect.

- (void)setPathToNetworkImage:(NSString *)pathToNetworkImage forDisplaySize:(CGSize)displaySize contentMode:(UIViewContentMode)contentMode cropRect:(CGRect)cropRect;

Discussion

Loads the image from the memory cache if possible, otherwise fires off a network request with this object's network image information.

Parameters

pathToNetworkImage	The network path to the image to be displayed.
cropRect	x/y, width/height are in percent coordinates. Valid range is [0..1] for all values.
displaySize	Used instead of the image's frame to determine the display size.
contentMode	The content mode used to crop and resize the image.

setPathToNetworkImage:cropRect:

Load an image from the network with a crop rect and the current frame as the display size.

- (void)setPathToNetworkImage:(NSString *)pathToNetworkImage cropRect:(CGRect)cropRect;

Discussion

Loads the image from the memory cache if possible, otherwise fires off a network request with this object's network image information.

Uses self.contentMode to crop and resize the image.

The image's current frame will be used as the display size for the image.

Parameters

pathToNetworkImage	The network path to the image to be displayed.
cropRect	x/y, width/height are in percent coordinates. Valid range is [0..1] for all values.

setPathToNetworkImage:contentMode:

Load an image from the network with a specific display size.

- (void)setPathToNetworkImage:(NSString *)pathToNetworkImage contentMode:(UIViewContentMode)contentMode;

Discussion

Loads the image from the memory cache if possible, otherwise fires off a network request with this object's network image information.

The image's current frame will be used as the display size for the image.

Parameters

pathToNetworkImage	The network path to the image to be displayed.
contentMode	The content mode used to crop and resize the image.

prepareForReuse

Kill any network requests and replace the displayed image with the initial image.

- (void)prepareForReuse;

Discussion

Prepares this view for reuse by cancelling any existing requests and displaying the initial image again.

networkImageViewDidStartLoading

A network request has begun.

- (void)networkImageViewDidStartLoading;

networkImageViewDidLoadImage:

The image has been loaded, either from the network or in-memory.

- (void)networkImageViewDidLoadImage:(UIImage *)image;

networkImageViewDidFailWithError:

A network request failed to load.

- (void)networkImageViewDidFailWithError:(NSError *)error;

nimbusOperationDidStart:

The operation has started executing.

- (void)nimbusOperationDidStart:(NIOperation *)operation;

Discussion

nimbusOperationWillFinish:

The operation is about to complete successfully.

- (void)nimbusOperationWillFinish:(NIOperation *)operation;

Discussion

This will not be called if the operation fails.

This will be called from within the operation's runloop and must be thread safe.

nimbusOperationDidFinish:

The operation has completed successfully.

- (void)nimbusOperationDidFinish:(NIOperation *)operation;

Discussion

This will not be called if the operation fails.

nimbusOperationDidFail:withError:

The operation failed in some way and has completed.

- (void)nimbusOperationDidFail:(NIOperation *)operation withError:(NSError *)error;

Discussion

operationDidFinish: will not be called.

Overview

Examples

Two basic methods for setting the display size of the network image

Use a different contentMode for the network image.

Tasks

Method Documentation

initialImage

Discussion

sizeForDisplay

Discussion

scaleOptions

Discussion

interpolationQuality

Discussion

imageMemoryCache

Discussion

networkOperationQueue

Discussion

maxAge

Discussion

delegate

initWithImage:

Discussion

setPathToNetworkImage:

Discussion

setPathToNetworkImage:forDisplaySize:

Discussion

setPathToNetworkImage:forDisplaySize:contentMode:

Discussion

setPathToNetworkImage:forDisplaySize:contentMode:cropRect:

Discussion

setPathToNetworkImage:cropRect:

Discussion

setPathToNetworkImage:contentMode:

Discussion

prepareForReuse

Discussion

networkImageViewDidStartLoading

networkImageViewDidLoadImage:

networkImageViewDidFailWithError:

nimbusOperationDidStart:

Discussion

nimbusOperationWillFinish:

Discussion

nimbusOperationDidFinish:

Discussion

nimbusOperationDidFail:withError:

Discussion