- Inherits from:
- NSObject
- Conforms to:
- NSCoding
- NSCopying
- NSObject (NSObject)
Declared in:
- AppKit/NSImage.h
An NSImage object contains an image that can be composited anywhere without first being drawn in any particular view. It manages the image by:
An image can be created from various types of data:
If data is placed in a file (for example, in an application bundle), the NSImage object can access the data whenever it's needed to create the image. If data is read from an NSData object, the NSImage object may need to store the data itself.
Images can also be defined by the program, in two ways:
An NSImage object can keep more than one representation of an image. Multiple representations permit the image to be customized for the display device. For example, different hand-tuned TIFF images can be provided for monochrome and color screens, and an EPS representation or a custom method might be used for printing. All representations are versions of the same image.
An NSImage returns an NSArray of its representations in response to a representations message. Each representation is a kind of NSImageRep object:
NSEPSImageRep | An image that can be recreated from EPS data that's either stored by the object or at a known location in the file system. |
NSBitmapImageRep | An image that can be recreated from bitmap or TIFF data. |
NSCustomImageRep | An image that can be redrawn by a method defined in the application. |
NSCachedImageRep | An image that has been rendered in an off-screen cache from data or instructions that are no longer available. The image in the cache provides the only data from which the image can be reproduced. |
You can define other NSImageRep subclasses for objects that render images from other types of source data. To make these new subclasses available to an NSImage object, they need to be added to the NSImageRep class registry by invoking the registerImageRepClass: class method. NSImage determines the data types that each subclass can support by invoking its imageUnfilteredFileTypes and imageUnfilteredPasteboardTypes methods.
The NSImage object will choose the representation that best matches the rendering device. By default, the choice is made according to the following set of ordered rules. Each rule is applied in turn until the choice of representation is narrowed to one.
By passing NO to the setPrefersColorMatch: method, you can have the NSImage try for a resolution match before a color match. This essentially inverts the first and second rules above.
If these rules fail to narrow the choice to a single representation-for example, if the NSImage has two color TIFF representations with the same resolution and depth-the chosen representation is system dependent.
When first asked to composite the image, the NSImage object chooses the representation that's best for the destination display device, as outlined above. It renders the representation in an off-screen window on the same device, then composites it from this cache to the desired location. Subsequent requests to composite the image use the same cache. Representations aren't cached until they're needed for compositing.
When printing, the NSImage tries not to use the cached image. Instead, it attempts to render on the printer-using the appropriate image data, or a delegated method-the best version of the image that it can. Only as a last resort will it image the cached bitmap.
Before an NSImage can be used, the size of the image must be set, in units of the base coordinate system. If a representation is smaller or larger than the specified size, it can be scaled to fit.
If the size of the image hasn't already been set when the
NSImage is provided with a representation, the size will be set
from the data. The bounding box is used to determine the size of
an NSEPSImageRep. The TIFF fields "ImageLength
"
and "ImageWidth
" are used to
determine the size of an NSBitmapImageRep.
Images have the horizontal orientation of the base coordinate system; they can't be rotated or horizontally flipped. When composited, an image maintains this orientation, no matter what coordinate system it's composited to. (The destination coordinate system is used only to determine the location of a composited image, not its size or orientation.) Images can be flipped in the vertical direction by using setFlipped:.
It's possible to refer to portions of an image when compositing by specifying a rectangle in the image's coordinate system, which is identical to the base coordinate system, except that the origin is at the lower left corner of the image.
An NSImage object can be identified either by its id or by a name. Assigning an NSImage a name adds it to a table kept by the class object; each name in the database identifies one and only one instance of the class. When you ask for an NSImage object by name (with the imageNamed: method), the class object returns the one from its database, which also includes all the system bitmaps provided by the Application Kit. If there's no object in the database for the specified name, the class object tries to create one by checking for a system bitmap of the same name, checking the name of the application's own image, and then checking for the image in the application's main bundle.
If a file matches the name, an NSImage is created from the data stored there. You can therefore create NSImage objects simply by including EPS, BMP, or TIFF data for them within the executable file, or in files inside the application's file package.
NSImage is designed to automatically take advantage of user-installed filter services for converting unsupported image file types to supported image file types. The class method imageFileTypes returns an array of all file types from which NSImage can create an instance of itself. This list includes all file types supported by registered subclasses of NSImageRep, and those types that can be converted to supported file types through a user-installed filter service.
NSCoding
- - encodeWithCoder:
- - initWithCoder:
NSCopying
- - copyWithZone:
- Initializing a new NSImage instance
- - initByReferencingFile:
- - initWithBitmapHandle:
- - initWithContentsOfFile:
- - initWithContentsOfURL:
- - initWithData:
- - initWithIconHandle:
- - initWithPasteboard:
- - initWithSize:
- Setting the size of the image
- - setSize:
- - size
- Referring to images by name
- + imageNamed:
- - setName:
- - name
- Specifying the image
- - addRepresentation:
- - addRepresentations:
- - lockFocus
- - lockFocusOnRepresentation:
- - unlockFocus
- Using the image
- - compositeToPoint:operation:
- - compositeToPoint:fromRect:operation:
- - dissolveToPoint:fraction:
- - dissolveToPoint:fromRect:fraction:
- Choosing which image representation to use
- - setPrefersColorMatch:
- - prefersColorMatch
- - setUsesEPSOnResolutionMismatch:
- - usesEPSOnResolutionMismatch
- - setMatchesOnMultipleResolution:
- - matchesOnMultipleResolution
- Getting the representations
- - bestRepresentationForDevice:
- - representations
- - removeRepresentation:
- Determining how the image is stored
- - setCachedSeparately:
- - isCachedSeparately
- - setDataRetained:
- - isDataRetained
- - setCacheDepthMatchesImageDepth:
- - cacheDepthMatchesImageDepth
- Determining how the image is drawn
- - isValid
- - setScalesWhenResized:
- - scalesWhenResized
- - setBackgroundColor:
- - backgroundColor
- - setFlipped:
- - isFlipped
- - drawRepresentation:inRect:
- - recache
- Assigning a delegate
- - setDelegate:
- - delegate
- Producing TIFF data for the image
- - TIFFRepresentation
- - TIFFRepresentationUsingCompression:factor:
- Managing NSImageRep subclasses
- + imageUnfilteredFileTypes
- + imageUnfilteredPasteboardTypes
- Testing image data sources
- + canInitWithPasteboard:
- + imageFileTypes
- + imagePasteboardTypes
+ (BOOL)canInitWithPasteboard:(NSPasteboard
*)pasteboard
NSImage uses the NSImageRep class method imageUnfilteredPasteboardTypes to find a class that can handle the data in pasteboard. When creating a subclass of NSImageRep that accepts image data from a non-default pasteboard type, override the imageUnfilteredPasteboardTypes method to notify NSImage of the pasteboard types your class supports.
See Also: + imagePasteboardTypes
+ (NSArray *)imageFileTypes
File
types are identified by extension. By default, the list returned
by this method contains "tiff
", "tif
",
"bmp
", and "eps
".
When creating a subclass of NSImageRep that accepts image data from non-default file types, override NSImageRep's imageUnfilteredFileTypes method to notify NSImage of the file types your class supports.
See Also: + imageUnfilteredFileTypes
+ (id)imageNamed:(NSString
*)name
If there's no known NSImage with name,
this method tries to create one by searching for image data in the
application's executable file and in the main bundle (see NSBundle's
class description for a description of how the bundle's contents
are searched). If a file contains data for more than one image, a
separate representation is created for each. If an image representation
can't be found for name, no object is created and nil
is
returned.
The preferred way to name an image is to ask for a name without the extension, but to include the extension for a file name.
One particularly useful image is referenced by the string "NSApplicationIcon". If you supply this string to imageNamed:, the returned image will be the application's own icon. Icons for other applications can be obtained through the use of methods declared in the NSWorkspace class.
The image returned by this method should not be freed, unless it's certain that no other objects reference it.
See Also: - setName:, - name, - iconForFile: (NSWorkspace), + imageFileTypes
+ (NSArray *)imagePasteboardTypes
By default,
the list returned by this method contains "NSPostScriptPboardType
"
and "NSTIFFPboardType
".
When creating a subclass of NSImageRep that accepts image data from non-default pasteboard types, override NSImageRep's imageUnfilteredPasteboardTypes method to notify NSImage of the pasteboard types your class supports.
See Also: + imageUnfilteredPasteboardTypes
+ (NSArray *)imageUnfilteredFileTypes
See Also: + imageFileTypes
+ (NSArray *)imageUnfilteredPasteboardTypes
See Also: + imagePasteboardTypes
- (void)addRepresentation:(NSImageRep
*)imageRep
Any representation added by this method is retained by the NSImage. Note that representations can't be shared among NSImages.
See Also: - representations, - removeRepresentation:
- (void)addRepresentations:(NSArray
*)imageReps
Representations added by this method are retained by the NSImage. Note that representations can't be shared among NSImages.
See Also: - representations, - removeRepresentation:
- (NSColor *)backgroundColor
The background color will be visible when the image is composited only if the image doesn't completely cover all the pixels within the area specified for its size.
- (NSImageRep *)bestRepresentationForDevice:(NSDictionary
*)deviceDescription
nil
,
the current device is assumed. "Choosing Representations" in
the class introduction outlines the process NSImage goes through
in order to determine the "best" representation for a given
device. For a list of dictionary keys and values appropriate to
display and print devices, see NSGraphics.h
. See Also: - representations, - prefersColorMatch
- (BOOL)cacheDepthMatchesImageDepth
- (void)compositeToPoint:(NSPoint)aPoint
fromRect:(NSRect)aRect
operation:(NSCompositingOperation)op
The source rectangle is specified relative to a coordinate system that has its origin at the lower left corner of the image, but is otherwise the same as the base coordinate system.
This method doesn't check to be sure that the rectangle encloses only portions of the image. Therefore, it can conceivably composite areas that don't properly belong to the image, if the aRect rectangle happens to include them. If this turns out to be a problem, you can prevent it from happening by having the NSImage cache its representations in their own individual windows (with the setCachedSeparately: method). In this case, the window's clipping path will prevent anything but the image from being composited.
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.
See Also: - dissolveToPoint:fromRect:fraction:
- (void)compositeToPoint:(NSPoint)aPoint
operation:(NSCompositingOperation)op
aPoint is specified in the current coordinate system-the coordinate system of the currently focused NSView-and designates where the lower left corner of the image will appear. The image will have the orientation of the base coordinate system, regardless of the destination coordinates. op should be one of the compositing operations as defined in dpsOpenStep.h.
The image is composited from its off-screen window cache. Since the cache isn't created until the image representation is first used, this method may need to render the image before compositing.
When printing, the compositing methods do not composite, but attempt to render the same image on the page that compositing would render on the screen, choosing the best available representation for the printer. The op argument is ignored.
See Also: - dissolveToPoint:fraction:
- (id)delegate
nil
if
no delegate has been set.- (void)dissolveToPoint:(NSPoint)aPoint
fraction:(float)aFloat
To slowly dissolve one image into another, this method (or dissolveToPoint:fromRect:fraction:) needs to be invoked repeatedly with an ever-increasing aFloat. Since aFloat refers to the fraction of the source image that's combined with the original destination (not the destination image after some of the source has been dissolved into it), the destination image should be replaced with the original destination before each invocation. This is best done in a buffered window before the results of the composite are flushed to the screen.
When printing, this method is identical to compositeToPoint:operation:. The delta argument is ignored.
- (void)dissolveToPoint:(NSPoint)aPoint
fromRect:(NSRect)aRect
fraction:(float)aFloat
When printing, this method is identical to compositeToPoint:fromRect:operation:. The aFloat argument is ignored.
- (BOOL)drawRepresentation:(NSImageRep
*)imageRep
inRect:(NSRect)rect
This method shouldn't be called directly; the NSImage uses it to cache and print its representations. By overriding it in a subclass, you can change how representations appear in the cache, and thus how they'll appear when composited. For example, your version of the method could scale or rotate the coordinate system, then send a message to super to perform this version.
If the background color is fully transparent and the image isn't being cached by the NSImage, the rectangle won't be filled before the representation draws.
- (id)initByReferencingFile:(NSString
*)filename
filename may
be a full or relative pathname, and should include an extension
that identifies the data type in the file. The mechanism that actually
creates the image representation for filename will
look for an NSImageRep subclass that handles that data type from
among those registered with NSImage. By default, the files handled
are those with the extensions "tiff
",
"tif
", "bmp
",
and "eps
".
After
finishing the initialization, this method returns self. However,
if the new instance can't be initialized, it's freed and nil
is
returned. Since this method doesn't actually create image representations
for the 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 file name. Note that if an image created with this method is archived, only the file name will be saved.
- (id)initWithBitmapHandle:(void
*)bitmap
nil
is
returned.- (id)initWithContentsOfFile:(NSString
*)filename
filename may
be a full or relative pathname, and should include an extension
that identifies the data type in the file. initWithContentsOfFile: will
look for an NSImageRep subclass that handles that data type from
among those registered with NSImage. By default, the files handled
are those with the extensions "tiff
",
"tif
", "bmp
",
and "eps
".
After
finishing the initialization, this method returns self. However,
if at least one image representation can't be created from the
contents of the specified file, the receiver is freed and nil
is returned.
- (id)initWithContentsOfURL:(NSURL
*)anURL
After
finishing the initialization, this method returns self. However,
if at least one image representation can't be created from the
contents of anURL, the receiver is
freed and nil
is returned.
- (id)initWithData:(NSData
*)data
nil
is
returned.- (id)initWithIconHandle:(void
*)icon
nil
is
returned.- (id)initWithPasteboard:(NSPasteboard
*)pasteboard
NSPostscriptPboardType
(NSEPSImageRep)
and NSTIFFPboardType
(NSBitmapImageRep).
If pasteboard contains an NSFilenamesPboardType
,
the file name should have an extension returned by one of the registered NSImageRep's imageUnfilteredFileTypes methods;
the default types supported are "tiff
",
"tif
", "bmp
",
(all in NSBitmapImageRep) and "eps
"
(NSEPSImageRep). If initWithPasteboard: is
able to create one or more image representations, it returns self.
Otherwise, the receiver is freed and nil
is
returned.
- (id)initWithSize:(NSSize)aSize
See Also: - setSize:
- (BOOL)isCachedSeparately
- (BOOL)isDataRetained
- (BOOL)isFlipped
- (BOOL)isValid
If no representations exist for the receiver, isValid first creates a cache with the default depth.
See Also: - initByReferencingFile:
- (void)lockFocus
A successful lockFocus message must be balanced by a subsequent unlockFocus message to the same NSImage. These messages bracket the code that draws the image.
If lockFocus is unable to focus on the representation, it raises an NSImageCacheException.
See Also: - bestRepresentationForDevice:, - isValid, - prefersColorMatch, - representations
- (void)lockFocusOnRepresentation:(NSImageRep
*)imageRepresentation
nil
, lockFocusOnRepresentation: acts
like lockFocus,
setting focus to the best representation for the NSImage. Otherwise, imageRepresentation must
be one of the representations in the NSImage.A successful lockFocusOnRepresentation: message must be balanced by a subsequent unlockFocus message to the same NSImage. These messages bracket the code that draws the image.
If lockFocusOnRepresentation: is unable to focus on the representation, it raises an NSImageCacheException.
See Also: - isValid
- (BOOL)matchesOnMultipleResolution
- (NSString *)name
nil
if
no name has been assigned.- (BOOL)prefersColorMatch
- (void)recache
If an image is likely not to be used again, it's a good idea to free its caches, since that will reduce that amount of memory consumed by your program and therefore improve performance.
- (void)removeRepresentation:(NSImageRep
*)imageRep
See Also: - representations
- (NSArray *)representations
- (BOOL)scalesWhenResized
Representations
created from data that specifies a size (for example, the "ImageLength
"
and "ImageWidth
" fields of a
TIFF representation or the bounding box of an EPS representation)
will have the size the data specifies, which may differ from the
size of the NSImage.
See Also: - setSize:
- (void)setBackgroundColor:(NSColor
*)aColor
See Also: - recache, - backgroundColor
- (void)setCacheDepthMatchesImageDepth:(BOOL)flag
See Also: - lockFocus, - recache
- (void)setCachedSeparately:(BOOL)flag
If an NSImage is to be resized frequently, it's more efficient to cache its representations separately.
This method doesn't invalidate any existing caches.
See Also: - recache
- (void)setDataRetained:(BOOL)flag
If an image representation is created using initByReferencingFile:, the only data retained is the name of the source file.
- (void)setDelegate:(id)anObject
- (void)setFlipped:(BOOL)flag
See Also: - recache
- (void)setMatchesOnMultipleResolution:(BOOL)flag
- (BOOL)setName:(NSString
*)aString
See Also: + imageNamed:
- (void)setPrefersColorMatch:(BOOL)flag
- (void)setScalesWhenResized:(BOOL)flag
Generally,
representations created through NSImage methods (such as initByReferencingFile:) have the
same size as the NSImage. However, a representation added with either addRepresentation: or addRepresentations: may
have a different size, and representations created from data that specifies
a size (for example, the "ImageLength
"
and "ImageWidth
" fields of a
TIFF representation or the bounding box of an EPS representation)
will have the size specified.
This method doesn't cause the receiving NSImage to recache itself when it is next composited.
See Also: - setSize:
- (void)setSize:(NSSize)aSize
The size of an NSImage must be set before it can be used. You can change the size of an NSImage after it has been used, but changing it invalidates all its caches and frees them. When the image is next composited, the selected representation will draw itself in an off-screen window to recreate the cache.
If the size of the image hasn't
already been set when the NSImage is provided with a representation, the
size will be set from the data. The bounding box is used to determine
the size of an NSEPSImageRep. The TIFF fields "ImageLength
"
and "ImageWidth
" are used to
determine the size of an NSBitmapImageRep.
See Also: - initWithSize:, - setScalesWhenResized:
- (void)setUsesEPSOnResolutionMismatch:(BOOL)flag
See Also: - setMatchesOnMultipleResolution:
- (NSSize)size
- (NSData *)TIFFRepresentation
- (NSData *)TIFFRepresentationUsingCompression:(NSTIFFCompression)comp
factor:(float)aFloat
If the specified compression isn't applicable, no compression is used. If a problem is encountered during generation of the TIFF, TIFFRepresentationUsingCompression:factor: raises an exception.
See Also: - TIFFRepresentationUsingCompression:factor: (NSBitmapImageRep)
- (void)unlockFocus
- (BOOL)usesEPSOnResolutionMismatch
See Also: - matchesOnMultipleResolution
- (NSImage *)imageDidNotDraw:(id)sender
inRect:(NSRect)aRect
nil
,
ornil
to
indicate that sender should give
up the attempt at drawing the image.