iOS Developer Library

Developer

UIKit Framework Reference UIImageView Class Reference

Options
Deployment Target:

On This Page
Language:

UIImageView

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 App Programming Guide for iOS.

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:

  • The UIImageView class is optimized to draw its images to the display. UIImageView does not call the drawRect: method of its subclasses. If your subclass needs to include custom drawing code, you should subclass the UIView class instead.

  • New image view objects are configured to disregard user events by default. If you want to handle events in a custom subclass of UIImageView, you must explicitly change the value of the userInteractionEnabled property to YEStrue after initializing the object.

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

Inheritance


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 2.0 and later.
  • Returns an image view initialized with the specified image.

    Declaration

    Swift

    init(image image: UIImage!)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    init(image image: UIImage!, highlightedImage highlightedImage: UIImage?)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • image image Property

    The image displayed in the image view.

    Declaration

    Swift

    var image: UIImage?

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    animationImages

  • The highlighted image displayed in the image view.

    Declaration

    Swift

    var highlightedImage: UIImage?

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • An array of UIImage objects to use for an animation.

    Declaration

    Swift

    var animationImages: [AnyObject]?

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    image
    contentMode (UIView)

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

    Declaration

    Swift

    var highlightedAnimationImages: [AnyObject]?

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    See Also

    highlightedImage
    contentMode (UIView)

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

    Declaration

    Swift

    var animationDuration: NSTimeInterval

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Specifies the number of times to repeat the animation.

    Declaration

    Swift

    var animationRepeatCount: Int

    Objective-C

    @property(nonatomic) NSInteger animationRepeatCount

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Starts animating the images in the receiver.

    Declaration

    Swift

    func startAnimating()

    Objective-C

    - (void)startAnimating

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Stops animating the images in the receiver.

    Declaration

    Swift

    func stopAnimating()

    Objective-C

    - (void)stopAnimating

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Returns a Boolean value indicating whether the animation is running.

    Declaration

    Swift

    func isAnimating() -> Bool

    Objective-C

    - (BOOL)isAnimating

    Return Value

    YEStrue if the animation is running; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var userInteractionEnabled: Bool

    Objective-C

    @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 NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value that determines whether the image is highlighted.

    Declaration

    Swift

    var highlighted: Bool

    Objective-C

    @property(nonatomic, getter=isHighlighted) BOOL highlighted

    Discussion

    This property determines whether the regular or highlighted images are used. When highlighted is set to YEStrue, 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 NOfalse, it will use the image and animationImages properties.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • tintColor tintColor Property

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

    Declaration

    Swift

    var tintColor: UIColor!

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.