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.

Definition at line 70 of file NINetworkImageView.h.

Inheritance diagram for NINetworkImageView:

Methods
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
NSString *	memoryCachePrefix property
NSString *	lastPathToNetworkImage 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

- NINetworkImageView: [read, write, retain]

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

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.

Definition at line 98 of file NINetworkImageView.h.

- NINetworkImageView: [read, write, assign]

A flag for enabling the resizing of images for display.

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.

Definition at line 99 of file NINetworkImageView.h.

- NINetworkImageView: [read, write, assign]

Options for modifying the way images are cropped when scaling.

By default this is NINetworkImageViewScaleToFitLeavesExcessAndScaleToFillCropsExcess.

See also:: NINetworkImageViewScaleOptions

Definition at line 100 of file NINetworkImageView.h.

- NINetworkImageView: [read, write, assign]

The interpolation quality to use when resizing the image.

The default value is kCGInterpolationDefault.

Definition at line 101 of file NINetworkImageView.h.

- NINetworkImageView: [read, write, retain]

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

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.

Definition at line 105 of file NINetworkImageView.h.

- NINetworkImageView: [read, write, retain]

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

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:

Definition at line 106 of file NINetworkImageView.h.

- NINetworkImageView: [read, write, assign]

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

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.

Definition at line 108 of file NINetworkImageView.h.

- NINetworkImageView: [read, write, copy]

A prefix for the memory cache key.

Prefixed to the memory cache key when looking for and storing this image in the memory cache.

This makes it possible to keep multiple versions of a network image from the same url in memory cropped and/or resized using different parameters. This can be useful if you're downloading a high resolution photo and using that same photo in various locations with different presentation requirements (a table view 50x50 icon and a larger 300x200 thumbnail for example).

By default this is nil.

Definition at line 110 of file NINetworkImageView.h.

- NINetworkImageView: [read, copy]

The last path assigned to the image view.

This property may be used to avoid setting the network path repeatedly and clobbering previous requests.

Note:: It is debatable whether this has any practical use and is being considered for removal.

Definition at line 111 of file NINetworkImageView.h.

- NINetworkImageView: [read, write, assign]

Delegate for state change notifications.

Definition at line 134 of file NINetworkImageView.h.

- (id) initWithImage: (UIImage *) image

Designated initializer.

Parameters:

image This will be the initialImage.

Definition at line 100 of file NINetworkImageView.m.

- (void) setPathToNetworkImage: (NSString *) pathToNetworkImage

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

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.

Definition at line 288 of file NINetworkImageView.m.

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

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

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.

Definition at line 297 of file NINetworkImageView.m.

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

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

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.

Definition at line 306 of file NINetworkImageView.m.

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

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

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.

Definition at line 333 of file NINetworkImageView.m.

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

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

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.

Definition at line 315 of file NINetworkImageView.m.

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

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

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.

Definition at line 324 of file NINetworkImageView.m.

- (void) prepareForReuse

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

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

Definition at line 420 of file NINetworkImageView.m.

- (void) networkImageViewDidStartLoading

A network request has begun.

Definition at line 264 of file NINetworkImageView.m.

- (void) networkImageViewDidLoadImage: (UIImage *) image

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

Definition at line 270 of file NINetworkImageView.m.

- (void) networkImageViewDidFailWithError: (NSError *) error

A network request failed to load.

Definition at line 276 of file NINetworkImageView.m.

- (void) nimbusOperationDidStart: (NIOperation *) operation

The operation has started executing.

- (void) nimbusOperationWillFinish: (NIOperation *) operation

The operation is about to complete successfully.

This will not be called if the operation fails.

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

- (void) nimbusOperationDidFinish: (NIOperation *) operation

The operation has completed successfully.

This will not be called if the operation fails.

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

The operation failed in some way and has completed.

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.

Methods

Method Documentation