The iOS framework that grows only as fast as its documentation
Classes | Enumerations
Nimbus Network Image

Classes

class  NINetworkImageView
 A network-enabled image view that consumes minimal amounts of memory. More...
 
protocol  <NINetworkImageViewDelegate>
 The image view delegate used to inform of state changes. More...
 

Enumerations

enum  NINetworkImageViewScaleOptions
 Flags for modifying the way cropping is handled when scaling images to fit or fill. More...
 

Overview

Image views that load images from the network and efficiently store the result in memory and on disk.

NINetworkImageViewExample1.png
The various available content modes.

Minimum Requirements

Required frameworks:

Minimum Operating System: iOS 4.0

Source located in src/networkimage/src

Presented below is an architectural overview of the Nimbus network image library.

NINetworkImageDesign1.png
NINetworkImage Design
  1. To begin using a network image view, simply create an instance of an NINetworkImageView and use it as you would a UIImageView. The initial image you assign to the view will be used as the "loading" image and must be a locally accessible image. Note that this image will not be cropped and resized in any way, so you should take care to crop and resize it beforehand as necessary.
  2. Once you have created your network image view and assigned the initial image, the next step is to load the network image. Call any of the setPathToNetworkImage methods to fire off a network request for the image on a separate thread.
  3. A new NINetworkImageRequest thread will spin off and initiate the request to the network.
  4. Once the image has been retrieved from the net, the thread crops and resizes the image depending on the presentation configurations specified by the image view. In this example, sizeForDisplay and cropImageForDisplay are enabled. In this step the image is resized to fit the aspect ratio of the display size.
  5. We then crop the image to fit the display frame.
  6. Upon completion of all image modifications, we complete the request and return only the modified image to the image view. This helps to reduce memory usage.
  7. The resized and cropped image is then stored in the in-memory image cache for quick access in the future.
  8. At last, the image view sets the new image and displays it.

Enumeration Type Documentation

NINetworkImageViewScaleOptions

Flags for modifying the way cropping is handled when scaling images to fit or fill.

NINetworkImageViewScaleOptions;
Discussion

By default the network image view will behave in the following way for these content modes:

  • UIViewContentModeScaleAspectFit: Leaves unfilled space as transparent.
  • UIViewContentModeScaleAspectFill: Crops any excess pixels.

The resulting image size will exactly match the display size.

You can modify this behavior using the following two flags which should be set using binary operators.

  NINetworkImageViewScaleToFitCropsRemainder
  The final image size will be shrunk to fit the image such that there is no transparency.

  NINetworkImageViewScaleToFillLeavesRemainder
  The final image size will be grown to include the excess pixels.

Examples

The following examples use this image:

clouds500x375.jpeg
Dimensions: 500x375

Default settings with UIViewContentModeScaleAspectFit

Result image (display size 100x100)

clouds100x100-fit.png
Fit image with default settings leaves transparent pixels. Size: 100x100.

Example code

imageView.scaleOptions = NINetworkImageViewScaleToFitLeavesExcessAndScaleToFillCropsExcess;
[imageView setPathToNetworkImage: @"http://farm2.static.flickr.com/1165/644335254_4b8a712be5.jpg"
forDisplaySize: CGSizeMake(100, 100)
contentMode: UIViewContentModeScaleAspectFit];
source image size: 500x375 [aspect ratio: 1.3333]
display size: 100x100 [aspect ratio: 1]
result image size: 100x100 [aspect ratio: 1] (transparency on the left and right edges)
image blt size: 100x75 [aspect ratio: 1.3333]

Default settings with UIViewContentModeScaleAspectFill

Result image (display size 100x100)

clouds100x100-fill.png
Fill image with default settings chops excess pixels. Size: 100x100.

Example code

[imageView setPathToNetworkImage: @"http://farm2.static.flickr.com/1165/644335254_4b8a712be5.jpg"
forDisplaySize: CGSizeMake(100, 100)
contentMode: UIViewContentModeScaleAspectFill];
source image size: 500x375 [aspect ratio: 1.3333]
display size: 100x100 [aspect ratio: 1]
result image size: 100x100 [aspect ratio: 1]
image blt size: 133x100 [aspect ratio: 1.3333]

NINetworkImageViewScaleToFitCropsExcess with UIViewContentModeScaleAspectFit

Result image (display size 100x100)

clouds100x100-fit-cropped.png
Fit image with NINetworkImageViewScaleToFitCropsExcess crops the transparency. Size: 100x75.

Example code

// Turn on NINetworkImageViewScaleToFitCropsExcess
imageView.scaleOptions |= NINetworkImageViewScaleToFitCropsExcess;
[imageView setPathToNetworkImage: @"http://farm2.static.flickr.com/1165/644335254_4b8a712be5.jpg"
forDisplaySize: CGSizeMake(100, 100)
contentMode: UIViewContentModeScaleAspectFill];
source image size: 500x375 [aspect ratio: 1.3333]
display size: 100x100 [aspect ratio: 1]
result image size: 100x75 [aspect ratio: 1.3333]
image blt size: 100x75 [aspect ratio: 1.3333]

NINetworkImageViewScaleToFillLeavesExcess with UIViewContentModeScaleAspectFill

Result image (display size 100x100)

clouds100x100-fill-excess.png
Fill image with NINetworkImageViewScaleToFillLeavesExcess leaves the excess. Size: 133x100.

Example code

// Turn on NINetworkImageViewScaleToFillLeavesExcess
imageView.scaleOptions |= NINetworkImageViewScaleToFillLeavesExcess;
[imageView setPathToNetworkImage: @"http://farm2.static.flickr.com/1165/644335254_4b8a712be5.jpg"
forDisplaySize: CGSizeMake(100, 100)
contentMode: UIViewContentModeScaleAspectFill];
source image size: 500x375 [aspect ratio: 1.3333]
display size: 100x100 [aspect ratio: 1]
result image size: 133x100 [aspect ratio: 1.3333]
image blt size: 133x100 [aspect ratio: 1.3333]