---

NSImage Class Reference

Overview

An NSImage object is a high-level class for manipulating image data. You use this class to load existing images or create new ones and composite them into a view or other image. This class works in conjunction with one or more image representation objects (subclasses of NSImageRep), which manage the actual image data.

Adopted Protocols

• encodeWithCoder:

• initWithCoder:

• copyWithZone:

Tasks

Initializing a New NSImage Object

• – initByReferencingFile:
• – initByReferencingURL:
• – initWithContentsOfFile:
• – initWithContentsOfURL:
• – initWithData:
• – initWithPasteboard:
• – initWithSize:
• – initWithIconRef:

Setting the Image Attributes

• – setSize:
• – size
• – isTemplate
• – setTemplate:

Referring to Images by Name

• + imageNamed:
• – setName:
• – name

Determining the Supported Image Types

• + canInitWithPasteboard:
• + imageTypes
• + imageUnfilteredTypes
• + imageFileTypes
• + imageUnfilteredFileTypes
• + imagePasteboardTypes
• + imageUnfilteredPasteboardTypes

Working With Image Representations

• – addRepresentation:
• – addRepresentations:
• – bestRepresentationForDevice:
• – representations
• – removeRepresentation:

Setting the Image Representation Selection Criteria

• – setPrefersColorMatch:
• – prefersColorMatch
• – setUsesEPSOnResolutionMismatch:
• – usesEPSOnResolutionMismatch
• – setMatchesOnMultipleResolution:
• – matchesOnMultipleResolution

Managing the Focus

• – lockFocus
• – lockFocusOnRepresentation:
• – unlockFocus

Drawing the Image

• – drawAtPoint:fromRect:operation:fraction:
• – drawInRect:fromRect:operation:fraction:
• – drawRepresentation:inRect:
• – compositeToPoint:operation:
• – compositeToPoint:fromRect:operation:
• – compositeToPoint:fromRect:operation:fraction:
• – compositeToPoint:operation:fraction:
• – dissolveToPoint:fraction:
• – dissolveToPoint:fromRect:fraction:
• – imageDidNotDraw:inRect:  delegate method

Working With Alignment Metadata

• – alignmentRect
• – setAlignmentRect:

Setting the Image Storage Options

• – setCachedSeparately:
• – isCachedSeparately
• – setDataRetained:
• – isDataRetained
• – setCacheDepthMatchesImageDepth:
• – cacheDepthMatchesImageDepth
• – cacheMode
• – setCacheMode:

Setting the Image Drawing Options

• – isValid
• – setScalesWhenResized:
• – scalesWhenResized
• – setBackgroundColor:
• – backgroundColor
• – setFlipped:
• – isFlipped
• – recache

Assigning a Delegate

• – setDelegate:
• – delegate

Producing TIFF Data for the Image

• – TIFFRepresentation
• – TIFFRepresentationUsingCompression:factor:

Managing Incremental Loads

• – cancelIncrementalLoad
• – image:didLoadPartOfRepresentation:withValidRows:  delegate method
• – image:didLoadRepresentation:withStatus:  delegate method
• – image:didLoadRepresentationHeader:  delegate method
• – image:willLoadRepresentation:  delegate method

Class Methods

canInitWithPasteboard:

Tests whether the receiver can create an instance of itself using pasteboard data.

+ (BOOL)canInitWithPasteboard:(NSPasteboard *)pasteboard

Parameters

pasteboard

The pasteboard containing the image data.

Return Value

YES if the receiver knows how to handle the data on the pasteboard; otherwise, NO.

Discussion

This method uses the NSImageRep class method imageUnfilteredPasteboardTypes to find a class that can handle the data in the specified pasteboard. If you create your own NSImageRep subclasses, override the imageUnfilteredPasteboardTypes method to notify NSImage of the pasteboard types your class supports.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + imagePasteboardTypes

Declared In

NSImage.h

imageFileTypes

Returns an array of strings identifying the image types supported by the registered NSImageRep objects.

+ (NSArray *)imageFileTypes

Return Value

An array of NSString objects, each of which identifies a single supported file type. The array can include encoded HFS file types as well as filename extensions.

Discussion

This list includes all file types supported by registered subclasses of NSImageRep plus those that can be converted to a supported type by a user-installed filter service. You can pass the array returned by this method directly to the runModalForTypes: method of NSOpenPanel.

When creating a subclass of NSImageRep, do not override this method. Instead, override the imageUnfilteredFileTypes method to notify NSImage of the file types your class supports directly.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + imageUnfilteredFileTypes

Declared In

NSImage.h

imageNamed:

Returns the NSImage instance associated with the specified name.

+ (id)imageNamed:(NSString *)name

Parameters

name

The name associated with the desired image.

Return Value

The NSImage object associated with the specified name, or nil if no such image was found.

Discussion

This method searches for named images in several places, returning the first image it finds matching the given name. The order of the search is as follows:

1. Search for an object whose name was set explicitly using the setName: method and currently resides in the image cache.

2. Search the application's main bundle for a file whose name matches the specified string. (For information on how the bundle is searched, see “Searching for Bundle Resources“ in Bundle Programming Guide.)

3. Search the Application Kit framework for a shared image with the specified name.

When looking for files in the application bundle, it is better (but not required) to include the filename extension in the name parameter. When naming an image with the setName: method, it is also convention not to include filename extensions in the names you specify. That way, you can easily distinguish between images you have named explicitly and those you want to load from the application's bundle.

One particularly useful image you can retrieve is your application's icon. This image is set by Cocoa automatically and referenced by the string @"NSApplicationIcon". Icons for other applications can be obtained through the use of methods declared in the NSWorkspace class. You can also retrieve some standard system images using Cocoa defined constants; for more information, see the Constants section of this class.

If an application is linked in Mac OS X v10.5 or later, images requested using this method and whose name ends in the word “Template” are automatically marked as template images.

The NSImage class keeps a reference to any named images in a table until the image name is cleared. Consequently you do not need to retain the returned image object unless its name could be cleared. You can clear an image object from the table by passing nil to the setName: method of the corresponding NSImage object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setName:
• – name
• – iconForFile: (NSWorkspace)
• + imageFileTypes

Declared In

NSImage.h

imagePasteboardTypes

Returns an array of strings identifying the pasteboard types supported directly by the registered NSImageRep objects.

+ (NSArray *)imagePasteboardTypes

Return Value

An array of NSString objects, each of which identifies a single supported pasteboard type. By default, this list contains the NSPDFPboardType, NSPICTPboardType, NSPostScriptPboardType, and NSTIFFPboardType types.

Discussion

This list includes all pasteboard types supported by registered subclasses of NSImageRep plus those that can be converted to a supported type by a user-installed filter service.

When creating a subclass of NSImageRep, do not override this method. Instead, override the imageUnfilteredPasteboardTypes method to notify NSImage of the pasteboard types your class supports.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + imageUnfilteredPasteboardTypes

Declared In

NSImage.h

imageTypes

Returns an array of UTI strings identifying the image types supported by the registered NSImageRep objects, either directly or through a user-installed filter service.

+ (NSArray *)imageTypes

Return Value

An array of NSString objects, each of which contains a UTI identifying a supported image type. Some sample image-related UTI strings include "public.image”, "public.jpeg”, and "public.tiff”. For a list of supported types, see UTCoreTypes.h.

Discussion

The returned list includes UTIs all file types supported by registered subclasses of NSImageRep plus those that can be converted to a supported type by a user-installed filter service. You can use the returned UTI strings with any method that supports UTIs.

You should not override this method directly. Instead, you should override the imageTypes method of NSImageRep.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• + imageUnfilteredTypes

Declared In

NSImage.h

imageUnfilteredFileTypes

Returns an array of strings identifying the file types supported directly by the registered NSImageRep objects.

+ (NSArray *)imageUnfilteredFileTypes

Return Value

An array of NSString objects, each of which identifies a single supported file type. File types are identified by file extension and HFS file types.

Discussion

The returned list does not contain pasteboard types that are available only through a user-installed filter service.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + imageFileTypes

Declared In

NSImage.h

imageUnfilteredPasteboardTypes

Returns an array of strings identifying the pasteboard types supported directly by the registered NSImageRep objects.

+ (NSArray *)imageUnfilteredPasteboardTypes

Return Value

An array of NSString objects, each of which identifies a single supported pasteboard type.

Discussion

The returned list does not contain pasteboard types that are supported only through a user-installed filter service.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + imagePasteboardTypes

Declared In

NSImage.h

imageUnfilteredTypes

Returns an array of UTI strings identifying the image types supported directly by the registered NSImageRep objects.

+ (NSArray *)imageUnfilteredTypes

Return Value

An array of NSString objects, each of which contains a UTI identifying a supported image type. Some sample image-related UTI strings include "public.image”, "public.jpeg”, and "public.tiff”. For a list of supported types, see UTCoreTypes.h.

Discussion

The returned list includes UTI strings only for those file types that are supported directly by registered subclasses of NSImageRep. It does not include types that are supported through user-installed filter services. You can use the returned UTI strings with any method that supports UTIs.

You should not override this method directly. Instead, you should override the imageUnfilteredTypes method of NSImageRep.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• + imageTypes

Declared In

NSImage.h

Instance Methods

addRepresentation:

Adds the specified image representation object to to the receiver.

- (void)addRepresentation:(NSImageRep *)imageRep

Parameters

imageRep

The image representation to add.

Discussion

After invoking this method, you may need to explicitly set features of the new image representation, such as the size, number of colors, and so on. This is true particularly when the NSImage object has multiple image representations to choose from. See NSImageRep and its subclasses for the methods you use to complete initialization.

Any representation added by this method is retained by the receiver. Image representations cannot be shared among multiple NSImage objects.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – representations
• – removeRepresentation:

Declared In

NSImage.h

addRepresentations:

Adds an array of image representation objects to the receiver.

- (void)addRepresentations:(NSArray *)imageReps

Parameters

imageReps

An array of NSImageRep objects.

Discussion

After invoking this method, you may need to explicitly set features of the new image representations, such as their size, number of colors, and so on. This is true particularly when the NSImage object has multiple image representations to choose from. See NSImageRep and its subclasses for the methods you use to complete initialization.

Representations added by this method are retained by the receiver. Image representations cannot be shared among multiple NSImage objects.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – representations
• – removeRepresentation:

Declared In

NSImage.h

alignmentRect

Returns alignment metadata that your code can use to position the image during layout.

- (NSRect)alignmentRect

Return Value

A rectangle containing the layout information for the image. If not set, the returned rectangle has an origin of (0, 0) and a size that matches the size of the image.

Discussion

The returned rectangle is merely a hint that your own code can use to determine positioning. The NSImage class does not use this rectangle during drawing.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setAlignmentRect:

Declared In

NSImage.h

backgroundColor

Returns the background color of image.

- (NSColor *)backgroundColor

Return Value

The background color of the image. The default color is transparent, as returned by the clearColor method of NSColor.

Discussion

The background color is visible only if the drawn image representation does not completely cover all of the pixels available for the image's current size.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSImage.h

bestRepresentationForDevice:

Returns the best representation for the device with the specified characteristics.

- (NSImageRep *)bestRepresentationForDevice:(NSDictionary *)deviceDescription

Parameters

deviceDescription

A dictionary of attributes for the specified device, or nil to specify the current device. For a list of dictionary keys and values appropriate to display and print devices, see the constants in NSScreen.

Return Value

The image representation that most closely matches the specified criteria.

Discussion

If deviceDescription is nil, this method uses the attributes of the device on which the content is to be drawn.

For information on how the "best" representation is chosen, see the Images chapter of Cocoa Drawing Guide.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – representations
• – prefersColorMatch
• – matchesOnMultipleResolution
• – usesEPSOnResolutionMismatch

Declared In

NSImage.h

cacheDepthMatchesImageDepth

Returns a Boolean value indicating whether an image's offscreen window caches use the same bit depth as the image data itself.

- (BOOL)cacheDepthMatchesImageDepth

Return Value

YES if the offscreen window caches use the same bit depth as the image data; otherwise, NO. The default value is NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setCacheDepthMatchesImageDepth:

Declared In

NSImage.h

cacheMode

Returns the receiver’s caching mode.

- (NSImageCacheMode)cacheMode

Return Value

A value indicating the caching mode. For a list of possible values, see NSImageCacheMode. This value is set to NSImageCacheDefault by default.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – setCacheMode:

Declared In

NSImage.h

cancelIncrementalLoad

Cancels the current download operation immediately, if the image is being incrementally loaded.

- (void)cancelIncrementalLoad

Discussion

This call has no effect if the image is not loading.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

NSImage.h

compositeToPoint:fromRect:operation:

Composites a portion of the image to the specified point in the current coordinate system.

- (void)compositeToPoint:(NSPoint)aPoint fromRect:(NSRect)srcRect operation:(NSCompositingOperation)op

Parameters

aPoint

The point at which to draw the image, specified in the current coordinate system.

srcRect

The portion of the image you want to draw, specified in the image's coordinate system.

op

The compositing operation to use when drawing the image to the screen. The supported compositing operations are described in “Constants.”

Discussion

This method draws the specified portion of the image without checking the bounds rectangle you pass into the srcRect parameter. If you specify a source rectangle that strays outside of the image's bounds rectangle, it is conceivable that you could composite parts of the offscreen cache window that do not belong to the receiver's image. You can avoid this problem by using the setCachedSeparately: method to force the image to be cached in its own offscreen window, which results in the content being clipped to the window rectangle. Alternatively, you can use the drawAtPoint:fromRect:operation:fraction: method, which checks the source rectangle before drawing.

During drawing, the image is composited from its offscreen window cache. Because the offscreen cache is not created until the image representation is first used, this method may need to render the image before compositing. Bitmap representations in particular are not cached until they are explicitly rendered. You can use the lockFocus and unlockFocus methods to force the cached version to be created.

Compositing part of an image is as efficient as compositing the whole image, but printing just part of an image is not. When printing, it’s necessary to draw the whole image and rely on a clipping path to be sure that only the desired portion appears.

During printing, this method ignores the op parameter. Even though this parameter is ignored, this method attempts to render the image as close as possible to its appearance when the compositing operation is used on the screen. In either case, the best image representation is chosen for the printing context.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – dissolveToPoint:fromRect:fraction:
• – drawAtPoint:fromRect:operation:fraction:

Declared In

NSImage.h

compositeToPoint:fromRect:operation:fraction:

Composites a portion of the image at the specified opacity to the current coordinate system.

- (void)compositeToPoint:(NSPoint)aPoint fromRect:(NSRect)srcRect operation:(NSCompositingOperation)op fraction:(CGFloat)delta

Parameters

aPoint

The point at which to draw the image, specified in the current coordinate system.

srcRect

The portion of the image you want to draw, specified in the image's coordinate system.

op

The compositing operation to use when drawing the image to the screen. The supported compositing operations are described in “Constants.”

delta

The desired opacity of the image, specified as a value between 0.0 and 1.0. A value of 0.0 renders the image totally transparent while 1.0 renders it fully opaque. Values larger than 1.0 are interpreted as 1.0.

Discussion

Behaves the same as compositeToPoint:fromRect:operation: except that you can specify the amount of opacity to use when drawing the image.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – dissolveToPoint:fromRect:fraction:
• – drawAtPoint:fromRect:operation:fraction:

Declared In

NSImage.h

compositeToPoint:operation:

Composites the entire image to the specified point in the current coordinate system.

- (void)compositeToPoint:(NSPoint)aPoint operation:(NSCompositingOperation)op

Parameters

aPoint

The point at which to draw the image, specified in the current coordinate system.

op

The compositing operation to use when drawing the image to the screen. The supported compositing operations are described in “Constants.”

Discussion

This method draws the receiver's best image representation at the specified point in the currently focused view. The entire image is drawn using its current size information.

During drawing, the image is composited from its offscreen window cache. Because the offscreen cache is not created until the image representation is first used, this method may need to render the image before compositing. Bitmap representations in particular are not cached until they are explicitly rendered. You can use the lockFocus and unlockFocus methods to force the cached version to be created.

During printing, this method ignores the op parameter. Even though this parameter is ignored, this method attempts to render the image as close as possible to its appearance when the compositing operation is used on the screen. In either case, the best image representation is chosen for the printing context.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – dissolveToPoint:fraction:
• – drawAtPoint:fromRect:operation:fraction:

Declared In

NSImage.h

compositeToPoint:operation:fraction:

Composites the entire image at the specified opacity in the current coordinate system.

- (void)compositeToPoint:(NSPoint)aPoint operation:(NSCompositingOperation)op fraction:(CGFloat)delta

Parameters

aPoint

The point at which to draw the image, specified in the current coordinate system.

op

The compositing operation to use when drawing the image to the screen. The supported compositing operations are described in “Constants.”

delta

The desired opacity of the image, specified as a value between 0.0 and 1.0. A value of 0.0 renders the image totally transparent while 1.0 renders it fully opaque. Values larger than 1.0 are interpreted as 1.0.

Discussion

Behaves the same as compositeToPoint:operation: except that you can specify the amount of opacity to use when drawing the image.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – dissolveToPoint:fraction:

Declared In

NSImage.h

delegate

Returns the delegate object of the receiver

- (id)delegate

Return Value

The current delegate object, or nil if no delegate has been set.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setDelegate:

Declared In

NSImage.h

dissolveToPoint:fraction:

Composites the entire image to the specified location using the NSCompositeSourceOver operator.

- (void)dissolveToPoint:(NSPoint)aPoint fraction:(CGFloat)delta

Parameters

aPoint

The point at which to draw the image, specified in the current coordinate system.

delta

The desired opacity of the image, specified as a value between 0.0 and 1.0. A value of 0.0 renders the image totally transparent while 1.0 renders it fully opaque. Values larger than 1.0 are interpreted as 1.0.

Discussion

Except for the choice of compositing operator, this method behaves in the same way as the compositeToPoint:operation: method. During printing, the delta parameter is ignored.

If the source image contains alpha information, this operation may promote the destination NSWindow object to contain alpha information.

To slowly dissolve this image onto another, you can invoke this method (or the dissolveToPoint:fromRect:fraction: method) repeatedly with an ever-increasing delta value. Because the delta parameter refers to the visible fraction of the source image, increasing the value causes the source image to replace the destination content gradually. You should generally perform this type of operation using a buffered window or other offscreen drawing environment.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSImage.h

dissolveToPoint:fromRect:fraction:

Composites a portion of the image to the specified location using the NSCompositeSourceOver operator.

- (void)dissolveToPoint:(NSPoint)aPoint fromRect:(NSRect)srcRect fraction:(CGFloat)delta

Parameters

aPoint

The point at which to draw the image, specified in the current coordinate system.

srcRect

The portion of the image you want to draw, specified in the image's coordinate system.

delta

The desired opacity of the image, specified as a value between 0.0 and 1.0. A value of 0.0 renders the image totally transparent while 1.0 renders it fully opaque. Values larger than 1.0 are interpreted as 1.0.

Discussion

Except for the choice of compositing operator, this method behaves in the same way as the compositeToPoint:fromRect:operation: method. During printing, the delta parameter is ignored.

If the source image contains alpha information, this operation may promote the destination NSWindow object to contain alpha information.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – dissolveToPoint:fraction:

Declared In

NSImage.h

drawAtPoint:fromRect:operation:fraction:

Draws all or part of the image at the specified point in the current coordinate system.

- (void)drawAtPoint:(NSPoint)point fromRect:(NSRect)srcRect operation:(NSCompositingOperation)op fraction:(CGFloat)delta

Parameters

point

The location in the current coordinate system at which to draw the image.

srcRect

The source rectangle specifying the portion of the image you want to draw. The coordinates of this rectangle are specified in the image's own coordinate system. If you pass in NSZeroRect, the entire image is drawn.

op

The compositing operation to use when drawing the image. See the NSCompositingOperation constants.

delta

The opacity of the image, specified as a value from 0.0 to 1.0. Specifying a value of 0.0 draws the image as fully transparent while a value of 1.0 draws the image as fully opaque. Values greater than 1.0 are interpreted as 1.0.

Discussion

The image content is drawn at its current resolution and is not scaled unless the CTM of the current coordinate system itself contains a scaling factor. The image is otherwise positioned and oriented using the current coordinate system.

Unlike the compositeToPoint:fromRect:operation: and compositeToPoint:fromRect:operation:fraction: methods, this method checks the rectangle you pass to the srcRect parameter and makes sure it does not lie outside the image bounds.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – dissolveToPoint:fraction:
• – drawInRect:fromRect:operation:fraction:

Declared In

NSImage.h

drawInRect:fromRect:operation:fraction:

Draws all or part of the image in the specified rectangle in the current coordinate system.

- (void)drawInRect:(NSRect)dstRect fromRect:(NSRect)srcRect operation:(NSCompositingOperation)op fraction:(CGFloat)delta

Parameters

dstRect

The rectangle in which to draw the image, specified in the current coordinate system.

srcRect

The source rectangle specifying the portion of the image you want to draw. The coordinates of this rectangle must be specified using the image's own coordinate system. If you pass in NSZeroRect, the entire image is drawn.

op

The compositing operation to use when drawing the image. See the NSCompositingOperation constants.

delta

The opacity of the image, specified as a value from 0.0 to 1.0. Specifying a value of 0.0 draws the image as fully transparent while a value of 1.0 draws the image as fully opaque. Values greater than 1.0 are interpreted as 1.0.

Discussion

If the srcRect and dstRect rectangles have different sizes, the source portion of the image is scaled to fit the specified destination rectangle. The image is otherwise positioned and oriented using the current coordinate system.

Unlike the compositeToPoint:fromRect:operation: and compositeToPoint:fromRect:operation:fraction: methods, this method checks the rectangle you pass to the srcRect parameter and makes sure it does not lie outside the image bounds.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – dissolveToPoint:fraction:
• – drawAtPoint:fromRect:operation:fraction:

Declared In

NSImage.h

drawRepresentation:inRect:

Draws the image using the specified image representation object.

- (BOOL)drawRepresentation:(NSImageRep *)imageRep inRect:(NSRect)dstRect

Parameters

imageRep

The image representation object to be drawn.

dstRect

The rectangle in which to draw the image representation, specified in the current coordinate system.

Return Value

YES if the image was successfully drawn; otherwise, returns NO.

Discussion

This method fills the specified rectangle with the image's current background color and then sends a message to the specified image representation asking if to draw itself. If the image supports the ability to scale itself when it is resized, this method sends a drawInRect: message; otherwise, it sends a drawAtPoint: message.

You should not call this method directly; an NSImage object uses it to cache and print its image representations. You can override this method to change the way images are rendered into their caches and onto the printed page. For example, you could scale or rotate the coordinate system before sending this message to super to continue rendering the image representation.

If the background color is fully transparent and the image data is not being cached, the specified rectangle is not to be filled before the representation draws.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – backgroundColor

Declared In

NSImage.h

initByReferencingFile:

Initializes and returns an NSImage instance and associates it with the specified file.

- (id)initByReferencingFile:(NSString *)filename

Parameters

filename

A full or relative path name specifying the file with the desired image data. Relative paths must be relative to the current working directory.

Return Value

An initialized NSImage instance, or nil if the new instance cannot be initialized.

Discussion

This method initializes the image object lazily. It does not actually open the specified file or create any image representations from its data until an application attempts to draw the image or request information about it.

The filename parameter should include the file extension that identifies the type of the image data. The mechanism that actually creates the image representation for filename looks for an NSImageRep subclass that handles that data type from among those registered with NSImage.

Because this method doesn’t actually create image representations for the image data, your application should do error checking before attempting to use the image; one way to do so is by invoking the isValid method to check whether the image can be drawn.

This method invokes setDataRetained: with an argument of YES, thus enabling it to hold onto its filename. When archiving an image created with this method, only the image's filename is written to the archive.

If the cached version of the image uses less memory than the original image data, the original data is flushed and the cached image is used. (This can occur for images whose resolution is greater than 72 dpi.) If you resize the image by less than 50%, the data is loaded in again from the file. If you expect the file to change or be deleted, you should use initWithContentsOfFile: instead.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSImage.h

initByReferencingURL:

Initializes and returns an NSImage instance and associates it with the specified URL.

- (id)initByReferencingURL:(NSURL *)url

Parameters

url

The URL identifying the image.

Return Value

An initialized NSImage instance, or nil if the new instance cannot be initialized.

Discussion

This method initializes the image object lazily. It does not attempt to retrieve the data from the specified URL or create any image representations from that data until an application attempts to draw the image or request information about it.

This url parameter should include a file extension that identifies the type of the image data. The mechanism that actually creates the image representation looks for an NSImageRep subclass that handles that data type from among those registered with NSImage.

Because this method doesn’t actually create image representations for the image data, your application should do error checking before attempting to use the image; one way to do so is by invoking the isValid method to check whether the image can be drawn.

This method invokes setDataRetained: with an argument of YES, thus enabling it to hold onto its URL. When archiving an image created with this method, only the image's URL is written to the archive.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

NSImage.h

initWithContentsOfFile:

Initializes and returns an NSImage instance with the contents of the specified file.

- (id)initWithContentsOfFile:(NSString *)filename

Parameters

filename

A full or relative path name specifying the file with the desired image data. Relative paths must be relative to the current working directory.

Return Value

An initialized NSImage instance, or nil if the method cannot create an image representation from the contents of the specified file.

Discussion

Unlike initByReferencingFile:, which initializes an NSImage object lazily, this method immediately opens the specified file and creates one or more image representations from its data.

The filename parameter should include the file extension that identifies the type of the image data. This method looks for an NSImageRep subclass that handles that data type from among those registered with NSImage.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSImage.h

initWithContentsOfURL:

Initializes and returns an NSImage instance with the contents of the specified URL.

- (id)initWithContentsOfURL:(NSURL *)aURL

Parameters

aUrl

The URL identifying the image.

Return Value

An initialized NSImage instance, or nil if the method cannot create an image representation from the contents of the specified URL.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSImage.h

initWithData:

Initializes and returns an NSImage instance with the contents of the specified NSData object.

- (id)initWithData:(NSData *)data

Parameters

data

The data object containing the image data.

Return Value

An initialized NSImage instance, or nil if the method cannot create an image representation from the contents of the specified data object.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSImage.h

initWithIconRef:

Initializes the image object with a Carbon-style icon resource.

- (id)initWithIconRef:(IconRef)iconRef

Parameters

iconRef

A reference to a Carbon icon resource.

Return Value

An initialized NSImage instance.

Discussion

Creates one or more bitmap image representations, one for each size icon contained in the IconRef data structure. This initialization method automatically retains the data in the iconRef parameter and loads the bitmaps from that data file lazily.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSImage.h

initWithPasteboard:

Initializes and returns an NSImage instance with data from the specified pasteboard.

- (id)initWithPasteboard:(NSPasteboard *)pasteboard

Parameters

pasteboard

The pasteboard containing the image data.

Return Value

An initialized NSImage instance, or nil if the method cannot create an image representation from the contents of the pasteboard.

Discussion

The specified pasteboard should contain a type supported by one of the registered NSImageRep subclasses. Table 1 lists the default pasteboard types and file extensions for several NSImageRep subclasses.

If the specified pasteboard contains the value NSFilenamesPboardType, each filename on the pasteboard should have an extension supported by one of the registered NSImageRep subclasses. You can use the imageUnfilteredFileTypes method of a given subclass to obtain the list of supported types for that class.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSImage.h

initWithSize:

Initializes and returns an NSImage instance whose size is set to the specified value.

- (id)initWithSize:(NSSize)aSize

Parameters

aSize

The size of the image, measured in points.

Return Value

An initialized NSImage instance.

Discussion

This method does not add any image representations to the image object.. It is permissible to initialize the receiver by passing a size of (0.0, 0.0); however, the receiver’s size must be set to a non-zero value before the NSImage object is used or an exception will be raised.

A