Deprecated NSImage Methods

A method identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in OS X v10.6

bestRepresentationForDevice:

Returns the best representation for the device with the specified characteristics. (Deprecated in OS X v10.6. Use bestRepresentationForRect:context:hints: instead.)

- (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 OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
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. (Deprecated in OS X v10.6. NSImage no longer caches to windows. A cache is now generated appropriate for the destination where an image is drawn. There is no replacement method.)

- (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 OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
NSImage.h

compositeToPoint:fromRect:operation:

Composites a portion of the image to the specified point in the current coordinate system. (Deprecated in OS X v10.6. Use drawInRect:fromRect:operation:fraction: instead.)

- (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 using 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 OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
NSImage.h

compositeToPoint:fromRect:operation:fraction:

Composites a portion of the image at the specified opacity to the current coordinate system. (Deprecated in OS X v10.6. Use drawInRect:fromRect:operation:fraction: instead.)

- (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, with 1.0 representing total opacity. Values larger than 1.0 are interpreted as 1.0. This method always expects to render something, so for values that are equal to or less than 0, this method renders at full opacity.

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 OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
NSImage.h

compositeToPoint:operation:

Composites the entire image to the specified point in the current coordinate system. (Deprecated in OS X v10.6. Use drawAtPoint:fromRect:operation:fraction: instead.)

- (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 OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
Declared In
NSImage.h

compositeToPoint:operation:fraction:

Composites the entire image at the specified opacity in the current coordinate system. (Deprecated in OS X v10.6. Use drawAtPoint:fromRect:operation:fraction: instead.)

- (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, with 1.0 representing total opacity. Values larger than 1.0 are interpreted as 1.0. This method always expects to render something, so for values that are equal to or less than 0, this method renders at full opacity.

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 OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
NSImage.h

dissolveToPoint:fraction:

Composites the entire image to the specified location using the NSCompositeSourceOver operator. (Deprecated in OS X v10.6. Use drawAtPoint:fromRect:operation:fraction: instead.)

- (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 OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
NSImage.h

dissolveToPoint:fromRect:fraction:

Composites a portion of the image to the specified location using the NSCompositeSourceOver operator. (Deprecated in OS X v10.6. Use drawInRect:fromRect:operation:fraction: instead.)

- (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 OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
Declared In
NSImage.h

isCachedSeparately

Returns a Boolean value indicating whether each image representation caches its contents in a separate offscreen window. (Deprecated in OS X v10.6. NSImage no longer caches to windows. There is no replacement method)

- (BOOL)isCachedSeparately
Return Value

YES if the image representations cache their content in separate offscreen windows; otherwise, NO. The default value is NO.

Discussion

If this method returns NO, it means that the image may be cached in a shared window but is not required to be. Images are cached in a shared window if they have the same general attributes, such as color space, resolution, and bit depth.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
NSImage.h

isDataRetained

Returns a Boolean value indicating whether the receiver retains its source image data. (Deprecated in OS X v10.6. In Mac OS v10.6 and later, NSImage no longer discards data in such a way that the original can no longer be reconstructed. There is no replacement method.)

- (BOOL)isDataRetained
Return Value

YES if the image retains its source data; otherwise, NO. The default value is NO with some exceptions, which are covered in the discussion.

Discussion

For image objects initialized using either the initByReferencingFile: or initByReferencingURL: method, this value is YES by default. The reason is that for these methods, data retention simply involves retaining the filename or URL.

Data retention increases the memory used by the NSImage object and its image representations.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
NSImage.h

isFlipped

Returns a Boolean value indicating whether the image uses a flipped coordinate system. (Deprecated in OS X v10.6. The flipped property of an image was widely misunderstood and has been deprecated. Use drawInRect:fromRect:operation:fraction:respectFlipped:hints: to draw respecting a context’s flipped status and lockFocusFlipped: to draw into a flipped image.)

- (BOOL)isFlipped
Return Value

YES if the image's coordinate system is flipped; otherwise, NO. The default is NO.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
NSImage.h

lockFocusOnRepresentation:

Prepares the specified image representation to receive drawing commands. (Deprecated in OS X v10.6. Use the code fragment shown in the special considerations below.)

- (void)lockFocusOnRepresentation:(NSImageRep *)imageRepresentation
Parameters
imageRepresentation

An image representation belonging to the receiver, or nil if you want the receiver to choose which image representation to use.

Discussion

This method sets the current drawing context to the area of the offscreen window used to cache the specified image representation's contents. Subsequent drawing commands are composited to this offscreen window. If the offscreen drawing area already has some content, any new drawing commands are composited with that content. This method does not modify the original image data directly.

If imageRepresentation is nil, this method acts like the lockFocus method, setting the focus to the best representation for the NSImage object.

A successful lockFocusOnRepresentation: message must be balanced with a matching unlockFocus message to the same NSImage object. These messages bracket the code that draws the image.

If lockFocusOnRepresentation: is unable to focus on the specified image representation, it raises an NSImageCacheException.

Special Considerations

This method is deprecated as it did not set up imageRepresentation as a drawing destination, it set the image up as a drawing destination, then drew imageRepresentation into it. You can replace this functionality with the following code fragment

[image lockFocus];
[imageRepresentation drawInRect:NSMakeRect(0,0,[image size].width, [image size].height)];
 
[image unlockFocus];
Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
See Also
Related Sample Code
Declared In
NSImage.h

scalesWhenResized

Returns a Boolean value indicating whether image representations are scaled to fit the receiver's size. (Deprecated in OS X v10.6. This method was related to caching behavior. In Mac OS X v10.6 and later, image caching is no longer necessary and as a result there is no replacement necessary.)

- (BOOL)scalesWhenResized
Return Value

YES if image representations are scaled to fit the receiver; otherwise, NO. The default value is NO.

Discussion

Images are not resized during drawing if this method returns YES. They are only resized when you change the size by sending the receiver a setSize: message.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
NSImage.h

setCacheDepthMatchesImageDepth:

Sets whether the receiver's offscreen window caches use the same bit depth as the image data itself. (Deprecated in OS X v10.6. NSImage no longer caches to windows. A cache is now generated appropriate for the destination where an image is drawn. There is no replacement method.)

- (void)setCacheDepthMatchesImageDepth:(BOOL)flag
Parameters
flag

YES if the offscreen caches use the same bit-depth associated with the image data; otherwise, NO to indicate they should use the default bit depth.

Discussion

This method does not cause the receiver to recache itself. The default depth limit is equal to the bit depth of the deepest screen on the system.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
Declared In
NSImage.h

setCachedSeparately:

Sets whether each image representation uses a separate offscreen window to cache its contents. (Deprecated in OS X v10.6. NSImage no longer caches to windows. There is no replacement method)

- (void)setCachedSeparately:(BOOL)flag
Parameters
flag

YES if you want each of the receiver's image representation objects to use a separate offscreen window for caching; otherwise, NO.

Discussion

If you specify NO, a representation can be cached together with other images, though in practice it might not be. This method does not invalidate any existing caches.

If you plan to resize an NSImage object frequently, it is usually more efficient to cache its representations separately. In some situations, you might also want to enable separate caching if you plan to use the compositeToPoint:fromRect:operation: or compositeToPoint:fromRect:operation:fraction:methods to draw the image.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
See Also
Declared In
NSImage.h

setDataRetained:

Sets whether the receiver retains its source image data. (Deprecated in OS X v10.6. In Mac OS v10.6 and later, NSImage no longer discards data in such a way that the original can no longer be reconstructed. There is no replacement method.)

- (void)setDataRetained:(BOOL)flag
Parameters
flag

YES if you want the source image data to be retained; otherwise NO.

Discussion

Retention of the source image data is important if the source of the image data could change, be moved, or be deleted. Data retention is also useful if you plan to resize an image frequently; otherwise, resizing occurs on a cached copy of the image, which can lose image quality during successive scaling operations. With data retention enabled, the image is resized from the original source data.

If the responsibility for drawing the image is delegated to another object, there is no reason to retain the image data. Similarly, if the source of the image data is not expected to change or you do not plan to resize the image, you do not need to retain the data. In fact, retaining the data leads to increased memory usage, which could have a negative impact on performance.

If you create your image object using the initByReferencingFile: method, the only data retained is the name of the source file.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
NSImage.h

setFlipped:

Sets whether the polarity of the y axis is inverted when drawing an image. (Deprecated in OS X v10.6. The flipped property of an image was widely misunderstood and has been deprecated. Use drawInRect:fromRect:operation:fraction:respectFlipped:hints: to draw respecting a context’s flipped status and lockFocusFlipped: to draw into a flipped image.)

- (void)setFlipped:(BOOL)flag
Parameters
flag

YES if you want the image data to be inverted before drawing; otherwise, NO.

Discussion

If flag is YES, the y-axis of the image's internal coordinate system is inverted, with the origin in the upper-left corner and the positive y axis extending downward. This method affects only the coordinate system used internally by the image and the orientation of the image when it is drawn; it does not affect the coordinate system used to specify the position of an image in a view. This method does not cause the receiver to recache itself.

If you set flag to YES and then lock focus and draw into the image, the content you draw is cached in the inverted (flipped) orientation. Changing the value for flag does not affect the orientation of the cached image.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
NSImage.h

setScalesWhenResized:

Sets whether different-sized image representations are scaled to fit the receiver's size. (Deprecated in OS X v10.6. This method was related to caching behavior. In Mac OS X v10.6 and later, image caching is no longer necessary and as a result there is no replacement necessary.)

- (void)setScalesWhenResized:(BOOL)flag
Parameters
flag

YES if image representations are scaled to fit; otherwise NO.

Discussion

Most images (especially those loaded from files and URLs) contain only a single image representation whose size is the same as the receiver. It is possible to add image representations using the addRepresentation: or addRepresentations: methods but doing so is rarely necessary because modern hardware is powerful enough to resize and scale images quickly. The only reason to consider creating new representations is if each representations contains a customized version of the image at a specific size. (TIFF images may also contain a thumbnail version of an image, which is stored using a separate image representation.) If you pass YES in the flag parameter, and subsequently send a setSize: message to the receiver, all such image representations would be scaled to the same size. Scaling of bitmap images usually results in the interpolation of the bitmap data.

This method does not invalidate the caches of any of the receiver's image representations. The caches are not invalidated until you change the image size using a setSize: message. Scaling affects only the cached offscreen data for a given image representation.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
NSImage.h