UIImageView Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
UIImageView.h
Related sample code

Overview

An image view object provides a view-based container for displaying either a single image or for animating a series of images. For animating the images, the UIImageView class provides controls to set the duration and frequency of the animation. You can also start and stop the animation freely.

When a UIImageView object displays one of its images, the actual behavior is based on the properties of the image and the view. If either of the image’s leftCapWidth or topCapHeight properties are non-zero, then the image is stretched according to the values in those properties. Otherwise, the image is scaled, sized to fit, or positioned in the image view according to the contentMode property of the view. It is recommended (but not required) that you use images that are all the same size. If the images are different sizes, each will be adjusted to fit separately based on that mode.

All images associated with a UIImageView object should use the same scale. If your application uses images with different scales, they may render incorrectly.

For information about basic view behaviors, see View Programming Guide for iOS.

State Preservation

In iOS 6 and later, if you assign a value to this view’s restorationIdentifier property, it attempts to preserve the frame of the displayed image. Specifically, the class preserves the values of the bounds, center, and transform properties of the view and the anchorPoint property of the underlying layer. During restoration, the image view restores these values so that the image appears exactly as before. For more information about how state preservation and restoration works, see iOS App Programming Guide.

Optimizing Image View Performance

Image views can perform two operations that are relatively expensive performance-wise: scaling the image and alpha compositing the image with lower layers. To maximize performance, you should:

  • Provide pre-scaled images where possible. For example, if you expect certain large images to be frequently displayed in a scaled-down thumbnail view, you might consider keeping the scaled-down images in a thumbnail cache.

  • Limit image size. Consider pre-scaling or tiling large images. The MVCNetworking sample code project (QImageScrollView.m) demonstrates how to determine what model of iOS device your software is running on. You can then use that information to help you determine what image dimension thresholds to use when scaling or tiling.

  • Disable alpha blending except where needed. Unless you are intentionally working with images that contain transparency (drawing UI elements, for example), you should generally mark the view as opaque by checking Opaque checkbox in the attributes inspector, or setting the opaque property on the view itself.

    For views that are not opaque, the device must perform a lot of unnecessary computation if alpha blending is enabled and the image contains an alpha channel. This performance impact is further magnified if you are using Core Animation shadows, because the shape of the shadow is then based on the contents of the view, and must be dynamically computed.

    To learn more about how alpha blending works, see “Customizing Transparency and Alpha Blending.”

Customizing Transparency and Alpha Blending

Transparency of an image view is defined by properties of both the underlying image and the view as follows:

  • If the Opaque flag is set (either programmatically or through Xcode’s inspector), the image is alpha blended with the background color of the view, and the view itself is opaque. The view’s Alpha setting is ignored.

  • If the Opaque flag is not set, the alpha channel for each pixel (or 1.0 if the image has no alpha channel) is multiplied by the view’s Alpha setting, and the resulting value determines the transparency for that pixel.

Subclassing Notes

Special Considerations

If you are writing a custom subclass of UIImageView, you should be aware of the following behaviors:

For more information about appearance and behavior configuration, see “Image Views”.

Tasks

Initializing a UIImageView Object

Image Data

Animating Images

Setting and Getting Attributes

Properties

animationDuration

The amount of time it takes to go through one cycle of the images.

@property(nonatomic) NSTimeInterval animationDuration
Discussion

The time duration is measured in seconds. The default value of this property is equal to the number of images multiplied by 1/30th of a second. Thus, if you had 30 images, the value would be 1 second.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIImageView.h

animationImages

An array of UIImage objects to use for an animation.

@property(nonatomic, copy) NSArray *animationImages
Discussion

The array must contain UIImage objects. You may use the same image object more than once in the array. Setting this property to a value other than nil hides the image represented by the image property. The value of this property is nil by default.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIImageView.h

animationRepeatCount

Specifies the number of times to repeat the animation.

@property(nonatomic) NSInteger animationRepeatCount
Discussion

The default value is 0, which specifies to repeat the animation indefinitely.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIImageView.h

highlighted

A Boolean value that determines whether the image is highlighted.

@property(nonatomic, getter=isHighlighted) BOOL highlighted
Discussion

This property determines whether the regular or highlighted images are used. When highlighted is set to YES, a non-animated image will use the highlightedImage property and an animated image will use the highlightedAnimationImages. If both of those properties are set to nil or if highlighted is set to NO, it will use the image and animationImages properties.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIImageView.h

highlightedAnimationImages

An array of UIImage objects to use for an animation when the view is highlighted.

@property(nonatomic, copy) NSArray *highlightedAnimationImages
Discussion

The array must contain UIImage objects. You may use the same image object more than once in the array. Setting this property to a value other than nil hides the image represented by the highlightedImage property. The value of this property is nil by default.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIImageView.h

highlightedImage

The highlighted image displayed in the image view.

@property(nonatomic, retain) UIImage *highlightedImage
Discussion

The initial value of this property is the image passed into the initWithImage:highlightedImage: method or nil if you initialized the receiver using a different method.

If the highlightedAnimationImages property contains a value other than nil, the contents of this property are not used.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIImageView.h

image

The image displayed in the image view.

@property(nonatomic, retain) UIImage *image
Discussion

The initial value of this property is the image passed into the initWithImage: method or nil if you initialized the receiver using a different method.

If the animationImages property contains a value other than nil, the contents of this property are not used.

Setting the image property does not change the size of a UIImageView. Call sizeToFit to adjust the size of the view to match the image.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIImageView.h

tintColor

A color used to tint template images in the view hierarchy.

@property(nonatomic, retain) UIColor *tintColor
Discussion

The default is nil. If a non-nil value is specified, the color is applied to any template images attached to the image view. For more information, see the renderingMode property on the UIImage class.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIImageView.h

userInteractionEnabled

A Boolean value that determines whether user events are ignored and removed from the event queue.

@property(nonatomic, getter=isUserInteractionEnabled) BOOL userInteractionEnabled
Discussion

This property is inherited from the UIView parent class. This class changes the default value of this property to NO.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIImageView.h

Instance Methods

initWithImage:

Returns an image view initialized with the specified image.

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

The initial image to display in the image view.

Return Value

An initialized image view object.

Discussion

This method adjusts the frame of the receiver to match the size of the specified image. It also disables user interactions for the image view by default.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIImageView.h

initWithImage:highlightedImage:

Returns an image view initialized with the specified regular and highlighted images.

- (id)initWithImage:(UIImage *)image highlightedImage:(UIImage *)highlightedImage
Parameters
image

The initial image to display in the image view.

highlightedImage

The image to display if the image view is highlighted.

Return Value

An initialized image view object.

Discussion

This method adjusts the frame of the receiver to match the size of the specified image. It also disables user interactions for the image view by default.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIImageView.h

isAnimating

Returns a Boolean value indicating whether the animation is running.

- (BOOL)isAnimating
Return Value

YES if the animation is running; otherwise, NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIImageView.h

startAnimating

Starts animating the images in the receiver.

- (void)startAnimating
Discussion

This method always starts the animation from the first image in the list.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIImageView.h

stopAnimating

Stops animating the images in the receiver.

- (void)stopAnimating
Availability
  • Available in iOS 2.0 and later.
Declared In
UIImageView.h