Class: UIImage
Overview
A UIImage object is a high-level way to display image data. You can create images from files, from Quartz image objects, or from raw image data you receive. The UIImage class also offers several options for drawing images to the current graphics context using different blend modes and opacity values.
Instance Attribute Summary (collapse)
-
- alignmentRectInsets
readonly
The alignment metadata used to position the image during layout.
-
- capInsets
readonly
The end-cap insets.
-
- CGImage
readonly
The underlying Quartz image data.
-
- CIImage
readonly
The underlying Core Image data.
-
- duration
readonly
Returns the time interval used to display an animated image.
-
- imageOrientation
readonly
The orientation of the receiver’s image.
-
- images
readonly
For an animated image, this property holds the complete array of UIImage objects that make up the animation.
-
- resizingMode
readonly
The resizing mode of the image.
-
- scale
readonly
The scale factor of the image.
-
- size
readonly
The dimensions of the image, taking orientation into account.
Class Method Summary (collapse)
-
+ animatedImageNamed:duration:
Creates and returns an animated image.
-
+ animatedImageWithImages:duration:
Creates and returns an animated image from an existing set of images.
-
+ animatedResizableImageNamed:capInsets:duration:
Creates and returns an animated image with end caps.
-
+ animatedResizableImageNamed:capInsets:resizingMode:duration:
Creates and returns an animated image with end caps and a specific resizing mode.
-
+ imageNamed:
Returns the image object associated with the specified filename.
-
+ imageWithCGImage:
Creates and returns an image object representing the specified Quartz image.
-
+ imageWithCGImage:scale:orientation:
Creates and returns an image object with the specified scale and orientation factors.
-
+ imageWithCIImage:
Creates and returns an image object that contains a Core Image object.
-
+ imageWithCIImage:scale:orientation:
Creates and returns an image object based on a Core Image object and the specified attributes.
-
+ imageWithContentsOfFile:
Creates and returns an image object by loading the image data from the file at the specified path.
-
+ imageWithData:
Creates and returns an image object that uses the specified image data.
-
+ imageWithData:scale:
Creates and returns an image object that uses the specified image data and scale factor.
Instance Method Summary (collapse)
-
- drawAsPatternInRect:
Draws a tiled Quartz pattern using the receiver’s contents as the tile pattern.
-
- drawAtPoint:
Draws the image at the specified point in the current context.
-
- drawAtPoint:blendMode:alpha:
Draws the entire image at the specified point using the custom compositing options.
-
- drawInRect:
Draws the entire image in the specified rectangle, scaling it as needed to fit.
-
- drawInRect:blendMode:alpha:
Draws the entire image in the specified rectangle and using the specified compositing options.
-
- imageWithAlignmentRectInsets:
Returns a new version of the image that uses the specified alignment insets.
-
- initWithCGImage:
Initializes and returns the image object with the specified Quartz image reference.
-
- initWithCGImage:scale:orientation:
Initializes and returns an image object with the specified scale and orientation factors.
-
- initWithCIImage:
Initializes and returns an image object with the specified Core Image object.
-
- initWithCIImage:scale:orientation:
Initializes and returns an image object with the specified Core Image object and properties.
-
- initWithContentsOfFile:
Initializes and returns the image object with the contents of the specified file.
-
- initWithData:
Initializes and returns the image object with the specified data.
-
- initWithData:scale:
Initializes and returns the image object with the specified data and scale factor.
-
- resizableImageWithCapInsets:
Creates and returns a new image object with the specified cap insets.
-
- resizableImageWithCapInsets:resizingMode:
Para This method is exactly the same as its counterpart resizableImageWithCapInsets: except that the resizing mode of the new image object can be explicitly declared.
Methods inherited from NSObject
#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version
Constructor Details
This class inherits a constructor from NSObject
Dynamic Method Handling
This class handles dynamic methods through the method_missing method in the class NSObject
Instance Attribute Details
- (UIEdgeInsets) alignmentRectInsets (readonly)
The alignment metadata used to position the image during layout. (read-only) You can use the inset values as a hint for specifying the image contents more precisely. For example, if you have a 20 x 20 pixel icon that includes a glow effect, you might set the insets to 2, 16} to indicate the position of the underlying icon without the glow effect. Objects that incorporate images can use these insets to place the image properly within their content.
- (UIEdgeInsets) capInsets (readonly)
The end-cap insets. (read-only) End caps specify the portion of an image that should not be resized when an image is stretched. This technique is used to implement buttons and other resizable image-based interface elements. When a button with end caps is resized, the resizing occurs only in the middle of the button, in the region between the end caps. The end caps themselves keep their original size and appearance.This property specifies the sizes of all four end caps. The middle (stretchable) portion consists of all the pixels that are not included in the end caps. These pixels are tiled, left-to-right, top-to-bottom to fill the remaining space.On a non-resizeable image, this property is set to UIEdgeInsetsZero; the image does not use end caps and the entire image is subject to stretching. To create a new image with a nonzero value for this property, use the resizableImageWithCapInsets: method. If your application specifies UIEdgeInsetsZero as the capInsets parameter, the entire image is tiled.
- (CGImageRef) CGImage (readonly)
The underlying Quartz image data. (read-only) If the image data has been purged because of memory constraints, invoking this method forces that data to be loaded back into memory. Reloading the image data may incur a performance penalty. If the UIImage object was initialized using a CIImage object, the value of the property is NULL.
- (CIImage) CIImage (readonly)
The underlying Core Image data. (read-only) If the UIImage object was initialized using a CGImageRef, the value of the property is nil.
- (NSTimeInterval) duration (readonly)
Returns the time interval used to display an animated image. (read-only) For a non-animated image, the value of this property is 0.0.
- (UIImageOrientation) imageOrientation (readonly)
The orientation of the receiver’s image. (read-only) Image orientation affects the way the image data is displayed when drawn. By default, images are displayed in the “up” orientation. If the image has associated metadata (such as EXIF information), however, this property contains the orientation indicated by that metadata. For a list of possible values for this property, see “UIImageOrientation.”
- (Array) images (readonly)
For an animated image, this property holds the complete array of UIImage objects that make up the animation. (read-only) For a non-animated image, the value of this property is nil.
- (UIImageResizingMode) resizingMode (readonly)
The resizing mode of the image. (read-only) The default value for this property is UIImageResizingModeTile. However, UIImage will implement the resizing mode the fastest way possible while still retaining the desired visual appearance. This means that if the region to be resized is a 1-pixel region and this property is set to UIImageResizingModeTile, the region will be stretched instead because the two are virtually indistinguishable for a region of that size and stretching is dramatically faster than tiling. To set the value of this property, you need to call either animatedResizableImageNamed:capInsets:resizingMode:duration: or resizableImageWithCapInsets:resizingMode: and specify the resizing mode using the resizingMode parameter. For a list of possible values for this property, see “UIImageResizingMode.”
- (Float) scale (readonly)
The scale factor of the image. (read-only) If you load an image from a file whose name includes the @2x modifier, the scale is set to 2.0. You can also specify an explicit scale factor when initializing an image from a Core Graphics image. All other images are assumed to have a scale factor of 1.0. If you multiply the logical size of the image (stored in the size property) by the value in this property, you get the dimensions of the image in pixels.
- (CGSize) size (readonly)
The dimensions of the image, taking orientation into account. (read-only) In iOS 4.0 and later, this value reflects the logical size of the image and is measured in points. In iOS 3.x and earlier, this value always reflects the dimensions of the image measured in pixels.
Class Method Details
+ (UIImage) animatedImageNamed(name, duration:duration)
Creates and returns an animated image. This method loads a series of files by appending a series of numbers to the base file name provided in the name parameter. For example, if the name parameter had ‘image’ as its contents, this method would attempt to load images from files with the names ‘image0’, ‘image1’ and so on all the way up to ‘image1024’. All images included in the animated image should share the same size and scale.
+ (UIImage) animatedImageWithImages(images, duration:duration)
Creates and returns an animated image from an existing set of images.
All images included in the animated image should share the same size and scale.+ (UIImage) animatedResizableImageNamed(name, capInsets:capInsets, duration:duration)
Creates and returns an animated image with end caps. This method loads a series of files by appending a series of numbers to the base file name provided in the name parameter. For example, if the name parameter had ‘image’ as its contents, this method would attempt to load images from files with the names ‘image0’, ‘image1’ and so on all the way up to ‘image1024’. All images included in the animated image should share the same size and scale.
+ (UIImage) animatedResizableImageNamed(name, capInsets:capInsets, resizingMode:resizingMode, duration:duration)
Creates and returns an animated image with end caps and a specific resizing mode. This method is exactly the same as its counterpart animatedResizableImageNamed:capInsets:duration: except that the resizing mode of the new image object can be explicitly declared. Since the resizing mode of an image is UIImageResizingModeTile by default, this method should only be used in place of its counterpart to create an animated image that needs to be resized with the UIImageResizingModeStretch resizing mode.
+ (UIImage) imageNamed(name)
Returns the image object associated with the specified filename. This method looks in the system caches for an image object with the specified name and returns that object if it exists. If a matching image object is not already in the cache, this method loads the image data from the specified file, caches it, and then returns the resulting object.On a device running iOS 4 or later, the behavior is identical if the device’s screen has a scale of 1.0. If the screen has a scale of 2.0, this method first searches for an image file with the same filename with an @2x suffix appended to it. For example, if the file’s name is button, it first searches for button@2x. If it finds a 2x, it loads that image and sets the scale property of the returned UIImage object to 2.0. Otherwise, it loads the unmodified filename and sets the scale property to 1.0. See iOS App Programming Guide for more information on supporting images with different scale factors.
+ (UIImage) imageWithCGImage(cgImage)
Creates and returns an image object representing the specified Quartz image. This method does not cache the image object. You can use the methods of the Core Graphics framework to create a Quartz image reference.
+ (UIImage) imageWithCGImage(imageRef, scale:scale, orientation:orientation)
Creates and returns an image object with the specified scale and orientation factors. This method does not cache the image object. You can use the methods of the Core Graphics framework to create a Quartz image reference.
+ (UIImage) imageWithCIImage(ciImage)
Creates and returns an image object that contains a Core Image object.
+ (UIImage) imageWithCIImage(ciImage, scale:scale, orientation:orientation)
Creates and returns an image object based on a Core Image object and the specified attributes.
+ (UIImage) imageWithContentsOfFile(path)
Creates and returns an image object by loading the image data from the file at the specified path. This method does not cache the image object.
+ (UIImage) imageWithData(data)
Creates and returns an image object that uses the specified image data. This method does not cache the image object.
+ (UIImage) imageWithData(data, scale:scale)
Creates and returns an image object that uses the specified image data and scale factor. This method does not cache the image object.
Instance Method Details
- (Object) drawAsPatternInRect(rect)
Draws a tiled Quartz pattern using the receiver’s contents as the tile pattern. This method uses a Quartz pattern to tile the image in the specified rectangle. The image is tiled with no gaps and the fill color is ignored. In the default coordinate system, the image tiles are situated down and to the right of the origin of the specified rectangle. This method respects any transforms applied to the current graphics context, however.
- (Object) drawAtPoint(point)
Draws the image at the specified point in the current context. This method draws the entire image in the current graphics context, respecting the image’s orientation setting. In the default coordinate system, images are situated down and to the right of the specified point. This method respects any transforms applied to the current graphics context, however.This method draws the image at full opacity using the kCGBlendModeNormal blend mode.
- (Object) drawAtPoint(point, blendMode:blendMode, alpha:alpha)
Draws the entire image at the specified point using the custom compositing options. This method draws the entire image in the current graphics context, respecting the image’s orientation setting. In the default coordinate system, images are situated down and to the right of the specified point. This method respects any transforms applied to the current graphics context, however.
- (Object) drawInRect(rect)
Draws the entire image in the specified rectangle, scaling it as needed to fit. This method draws the entire image in the current graphics context, respecting the image’s orientation setting. In the default coordinate system, images are situated down and to the right of the origin of the specified rectangle. This method respects any transforms applied to the current graphics context, however.This method draws the image at full opacity using the kCGBlendModeNormal blend mode.
- (Object) drawInRect(rect, blendMode:blendMode, alpha:alpha)
Draws the entire image in the specified rectangle and using the specified compositing options. This method scales the image as needed to make it fit in the specified rectangle. This method draws the image in the current graphics context, respecting the image’s orientation setting. In the default coordinate system, images are situated down and to the right of the origin of the specified rectangle. This method respects any transforms applied to the current graphics context, however.
- (UIImage) imageWithAlignmentRectInsets(alignmentInsets)
Returns a new version of the image that uses the specified alignment insets.
- (Object) initWithCGImage(CGImage)
Initializes and returns the image object with the specified Quartz image reference.
- (Object) initWithCGImage(imageRef, scale:scale, orientation:orientation)
Initializes and returns an image object with the specified scale and orientation factors
- (Object) initWithCIImage(ciImage)
Initializes and returns an image object with the specified Core Image object.
- (Object) initWithCIImage(ciImage, scale:scale, orientation:orientation)
Initializes and returns an image object with the specified Core Image object and properties.
- (Object) initWithContentsOfFile(path)
Initializes and returns the image object with the contents of the specified file. This method loads the image data into memory and marks it as purgeable. If the data is purged and needs to be reloaded, the image object loads that data again from the specified path.
- (Object) initWithData(data)
Initializes and returns the image object with the specified data. The data in the data parameter must be formatted to match the file format of one of the system’s supported image types.
- (Object) initWithData(data, scale:scale)
Initializes and returns the image object with the specified data and scale factor. The data in the data parameter must be formatted to match the file format of one of the system’s supported image types.
- (UIImage) resizableImageWithCapInsets(capInsets)
Creates and returns a new image object with the specified cap insets. You use this method to add cap insets to an image or to change the existing cap insets of an image. In both cases, you get back a new image and the original image remains untouched. During scaling or resizing of the image, areas covered by a cap are not scaled or resized. Instead, the pixel area not covered by the cap in each direction is tiled, left-to-right and top-to-bottom, to resize the image. This technique is often used to create variable-width buttons, which retain the same rounded corners but whose center region grows or shrinks as needed. For best performance, use a tiled area that is a 1x1 pixel area in size.
- (UIImage) resizableImageWithCapInsets(capInsets, resizingMode:resizingMode)
Para This method is exactly the same as its counterpart resizableImageWithCapInsets: except that the resizing mode of the new image object can be explicitly declared. You should only call this method in place of its counterpart if you specifically want your image to be resized with the UIImageResizingModeStretch resizing mode.