iOS Developer Library

Developer

UIKit Framework Reference UIImageView Class Reference

Options
Deployment Target:

On This Page
Language:

UIImageView

A UIImageView object displays a single image or a sequence of animated images in your interface. Image views let you efficiently draw any image that can be specified using a UIImage object. For example, you can use this class to display the contents of many standard image files, such as JPEG and PNG files. You can configure image views programmatically or in your storyboard file and change the images they display at runtime. For animated images, you can also use the methods of this class to start and stop the animation and specify other animation parameters.

image: ../Art/uiimageview_image_2x.png

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

Understanding How Images Are Scaled

An image view uses its contentMode property and the configuration of the image itself to determine how to display the image. It is best to specify images whose dimensions match the dimensions of the image view exactly, but image views can scale your images to fit all or some of the available space. If the size of the image view itself changes, it automatically scales the image as needed.

For an image without cap insets, the presentation of the image is determined solely by the image view’s contentMode property. The UIViewContentModeScaleAspectFit and UIViewContentModeScaleAspectFill modes scale the image to fit or fill the space while maintaining the image’s original aspect ratio. The UIViewContentModeScaleToFill value scales the image without regard to the original aspect ratio, which can cause the image to appear distorted. Other content modes place the image at the appropriate location in the image view’s bounds without scaling it.

For a resizable image with cap insets, those insets affect the final appearance of the image. Specifically, cap insets define which parts of the image may be scaled and in which directions. You can create a resizable image that stretches using the resizableImageWithCapInsets:resizingMode: method of UIImage. When using an image of this type, you typically set the image view’s content mode to UIViewContentModeScaleToFill so that the image stretches in the appropriate places and fills the image view’s bounds.

For tips on how to prepare images, see Tracking Down Problems with Your Image View. For more information on creating resizable images with cap insets, see UIImage Class Reference.

Determining the Final Transparency of the Image

Images are composited onto the image view’s background and are then composited into the rest of the window. Any transparency in the image allows the image view’s background to show through. Similarly, any further transparency in the

of the image is dependent on the transparency of the image view and the transparency of the UIImage object it displays. When the image view and its image both have transparency, the image view uses alpha blending to combine the two.

  • The image is composited onto the image view’s background.

  • Para

  • If the image view’s opaque property is YEStrue, the image’s pixels are composited on top of the image view’s background color and the alpha property of the image view is ignored.

  • If the image view’s opaque property is NOfalse, the alpha value of each pixel is multiplied by the image view’s alpha value, with the resulting value becoming the actual transparency value for that pixel. If the image does not have an alpha channel, the alpha value of each pixel is assumed to be 1.0.

Animating a Sequence of Images

An image view can store an animated image sequence and play all or part of that sequence. You specify an image sequence as an array of UIImage objects and assign them to the animationImages property. Once assigned, you can use the methods and properties of this class to configure the animation timing and to start and stop the animation.

Consider the following tips when displaying a sequence of animated images:

  • All images in the sequence should have the same size. When scaling is required, the image view scales each image in the sequence separately. If the images are different sizes, scaling may not yield the results you want.

  • All images in the sequence should use the same content scale factor. Make sure the scale property of each image contains the same value.

Responding to Touch Events

Image views ignore user events by default. Normally, you use image views only to present visual content in your interface. If you want an image view to handle user interactions as well, change the value of its userInteractionEnabled property to YEStrue. After doing that, you can attach gesture recognizers or use any other event handling techniques to respond to touch events or other user-initiated events.

For more information about handling events, see Event Handling Guide for iOS.

Tips for Improving Performance

Image scaling and alpha blending are two relatively expensive operations that can impact your app’s performance. To maximize performance of your image view code, consider the following tips:

  • Cache scaled versions of frequently used images. If you expect certain large images to be displayed frequently in a scaled-down thumbnail view, consider creating the scaled-down images in advance and storing them in a thumbnail cache. Doing so alleviates the need for each image view to scale them separately.

  • Use images whose size is close to the size of the image view. Rather than assigning a large image to an image view, created a scaled version that matches the current size of the image view. You can also create a resizable image object using the UIImageResizingModeTile option, which tiles the image instead of scaling it.

  • Make your image view opaque whenever possible. Unless you are intentionally working with images that contain transparency (drawing UI elements, for example), make sure the opaque property of your image view is set to YEStrue. For more information about how transparency is determined, see Determining the Final Transparency of the Image.

Debugging Issues with Your Image View

If your image view is not displaying what you expected, use the following tips to help diagnose the problem:

  • Load images using the correct method. Use the imageNamed:inBundle:compatibleWithTraitCollection: method of UIImage to load images from asset catalogs or your app’s bundle. For images outside of your app’s bundle, use the imageWithContentsOfFile: method.

  • Do not use image views for custom drawing. TheUIImageView class does not draw its content using the drawRect: method. Use image views only to present images. To do custom drawing involving images, subclass UIView directly and draw your image there.

Interface Builder Attributes

Table 1 lists the attributes that you configure for image views in Interface Builder.

Table 1Image view attributes

Attribute

Discussion

Image

The image to display. You can specify any image in your Xcode project, including standalone images and those in image assets. To set this attribute programmatically, use the image or animationImages property.

Highlighted

The image to display when the image view is highlighted. To set this attribute programmatically, use the highlightedImage or highlightedAnimationImages property.

State

The initial state of the image. Use this attribute to mark the image as highlighted. To set this attribute programmatically, use the highlighted property.

Internationalization

Internationalization of image views is automatic if your view displays only static images loaded from your app bundle. If you are loading images programmatically, you are at least partially responsible for loading the correct image.

  • For resources in your app bundle, you do this by specifying the name in the attributes inspector or by calling the imageNamed: class method on UIImage to obtain the localized version of each image.

  • For images that are not in your app bundle, your code must do the following:

    1. Determine which image to load in a manner specific to your app, such as providing a localized string that contains the URL.

    2. Load that image by passing the URL or data for the correct image to an appropriate UIImage class method, such as imageWithData: or imageWithContentsOfFile:.

For more information, see Internationalization and Localization Guide.

Accessibility

Image views are accessible by default. The default accessibility traits for a image view are Image and User Interaction Enabled.

For more information about making iOS controls accessible, see the accessibility information in UIControl Class Reference. For general information about making your interface accessible, see Accessibility Programming Guide for iOS.

State Preservation

When you assign a value to an image 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.

  • 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. You may specify an image object that contains an animated sequence of images.

    Return Value

    An initialized image view object.

    Discussion

    The image you specified is used to configure the initial size of the image view itself. Use constraints and the image view’s content mode to adjust the image view’s final size onscreen. This method disables user interactions for the image view by setting the userInteractionEnabled property to NOfalse.

    If you specify an animated image whose duration is greater than 0, the image view automatically starts playing the animation.

    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. You may specify an image object that contains an animated sequence of images.

    highlightedImage

    The image to display when the image view is highlighted. You may specify an image object that contains an animated sequence of images.

    Return Value

    An initialized image view object.

    Discussion

    The images you specify are used to configure the initial size of the image view itself. Use constraints and the image view’s content mode to adjust the image view’s final size onscreen. This method disables user interactions for the image view by setting the userInteractionEnabled property to NOfalse.

    If you specify an animated image whose duration is greater than 0, the image view automatically starts playing the animation.

    Availability

    Available in iOS 3.0 and later.

  • The image displayed in the image view.

    Declaration

    Swift

    var image: UIImage?

    Objective-C

    @property(nonatomic, strong) UIImage *image

    Discussion

    This property contains the main image displayed by the image view. This image is displayed when the image view is in its natural state. When highlighted, the image view displays the image in its highlightedImage property instead. If that property is set to nil, the image view applies a default highlight to this image. If the animationImages property contains a valid set of images, those images are used instead.

    Changing the image in this property does not automatically change the size of the image view. After setting the image, call the sizeToFit method to recompute the image view’s size based on the new image and the active constraints.

    This property is set to the image you specified at initialization time. If you did not use the initWithImage: or initWithImage:highlightedImage: method to initialize your image view, the initial value of this property is nil.

    Availability

    Available in iOS 2.0 and later.

  • The highlighted image displayed in the image view.

    Declaration

    Swift

    var highlightedImage: UIImage?

    Objective-C

    @property(nonatomic, strong) UIImage *highlightedImage

    Discussion

    The image in this property is displayed when the image view’s highlighted property is YEStrue. If the highlightedAnimationImages property contains a valid set of images, those image are used instead.

    This property is set to the image (if any) you specified at initialization time. If you did not use the initWithImage:highlightedImage: method to initialize your image view, the initial value of this property is nil.

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    var animationImages: [UIImage]?

    Objective-C

    @property(nonatomic, copy) NSArray <UIImage *> *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

    image

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

    Declaration

    Swift

    var highlightedAnimationImages: [UIImage]?

    Objective-C

    @property(nonatomic, copy) NSArray <UIImage *> *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.

    See Also

    highlightedImage

  • 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 0.0, which causes the image view to use a duration equal to the number of images multiplied by 1/30th of a second. Thus, if you had 30 images, the duration would be 1 second.

    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.

    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.

    Availability

    Available in iOS 2.0 and later.

  • Stops animating the images in the receiver.

    Declaration

    Swift

    func stopAnimating()

    Objective-C

    - (void)stopAnimating

    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.

    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.

    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.

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    var tintColor: UIColor!

    Objective-C

    @property(nonatomic, strong) 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.