UIImageView Class Reference

Inherits from
UIView : UIResponder : NSObject
Conforms to
NSCoding (UIView)
UIAppearance (UIView)
UIAppearanceContainer (UIView)
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
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.

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 YES after initializing the object.

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.

Subclassing Notes

Special Considerations

The UIImageView class is optimized to draw its images to the display. UIImageView will not call the drawRect: method of a subclass. If your subclass needs custom drawing code, it is recommended you use UIView as the base class.

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.
Related Sample Code
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.
See Also
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.
See Also
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.
See Also
Related Sample Code
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.
Related Sample Code
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


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...