| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in Mac OS X v10.0 and later. |
| Companion guide | |
| Declared in | NSImageRep.h |
| Related sample code |
The NSImageRep class is a semiabstract superclass (“semi” because it has some instance variables and implementation of its own). Each of its subclasses knows how to draw an image from a particular kind of source data. While an NSImageRep subclass can be used directly, it is typically through an NSImage object. An NSImage object manages a group of image representations, choosing the best one for the current output device.
+ imageRepsWithContentsOfFile:
+ imageRepsWithPasteboard:
+ imageRepsWithContentsOfURL:
+ imageRepWithContentsOfFile:
+ imageRepWithPasteboard:
+ imageRepWithContentsOfURL:
+ canInitWithData:
+ canInitWithPasteboard:
+ imageTypes
+ imageUnfilteredTypes
+ imageFileTypes
+ imagePasteboardTypes
+ imageUnfilteredFileTypes
+ imageUnfilteredPasteboardTypes
– bitsPerSample
– colorSpaceName
– hasAlpha
– isOpaque
– pixelsHigh
– pixelsWide
– setAlpha:
– setBitsPerSample:
– setColorSpaceName:
– setOpaque:
– setPixelsHigh:
– setPixelsWide:
+ imageRepClassForType:
+ imageRepClassForData:
+ imageRepClassForFileType:
+ imageRepClassForPasteboardType:
+ registeredImageRepClasses
+ registerImageRepClass:
+ unregisterImageRepClass:
Returns a Boolean value indicating whether the receiver can initialize itself from the specified data.
+ (BOOL)canInitWithData:(NSData *)data
The image data.
YES if the receiver understands the format of the specified data and can use it to initialize itself; otherwise, NO.
This method should be overridden by subclasses. Note that this method does not need to do a comprehensive check of the image data; it should return NO only if it knows it cannot initialize itself from the data.
NSImageRep.hReturns a Boolean value indicating whether the receiver can initialize itself from the data on the specified pasteboard.
+ (BOOL)canInitWithPasteboard:(NSPasteboard *)pasteboard
The pasteboard containing the image data.
YES if the receiver understands the format of the specified data and can use it to initialize itself; otherwise, NO.
This method invokes the imageUnfilteredPasteboardTypes class method and checks the list of types returned by that method against the data types in pasteboard. If it finds a match, it returns YES. When creating a subclass of NSImageRep that accepts image data from a non-default pasteboard type, override the imageUnfilteredPasteboardTypes method to assure this method returns the correct response.
NSImageRep.h
Returns the file types supported by NSImageRep or one of its subclasses.
+ (NSArray *)imageFileTypes
An array of NSString objects, each of which contains a filename extension or HFS file type of a supported format.
The list includes both those types returned by the imageUnfilteredFileTypes class method plus those that can be converted to a supported type by a user-installed filter service. The returned file types can include encoded HFS file types as well as filename extensions.
Don’t override this method when subclassing NSImageRep—it always returns a valid list for any subclass of NSImageRep that correctly overrides the imageUnfilteredFileTypes method.
NSImageRep.hReturns the pasteboard types supported by NSImageRep or one of its subclasses.
+ (NSArray *)imagePasteboardTypes
An array of NSString objects, each of which contains a supported pasteboard format.
The list includes both those types returned by the imageUnfilteredPasteboardTypes class method plus those that can be converted to a supported type by a user-installed filter service. Don’t override this method when subclassing NSImageRep—it always returns a valid list for any subclass of NSImageRep that correctly overrides the imageUnfilteredPasteboardTypes method.
NSImageRep.hReturns the NSImageRep subclass that handles the specified type of data.
+ (Class)imageRepClassForData:(NSData *)data
The image data.
A Class object for the image representation that can handle the data, or nil if no image representation could handle the data.
NSImageRep.hReturns the NSImageRep subclass that handles data with the specified type.
+ (Class)imageRepClassForFileType:(NSString *)type
A string containing the filename extension or an encoded HFS type.
A Class object for the image representation that can handle the type of data, or nil if no image representation could handle the type.
NSImageRep.hReturns the NSImageRep subclass that handles data with the specified pasteboard type.
+ (Class)imageRepClassForPasteboardType:(NSString *)type
The pasteboard type.
A Class object for the image representation that can handle the specified pasteboard type, or nil if no image representation could handle the type.
NSImageRep.hReturns the NSImageRep subclass that handles image data for the specified UTI.
+ (Class)imageRepClassForType:(NSString *)type
The UTI string identifying the desired 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.
A Class object for the image representation that can handle the UTI, or nil if no image representation could handle the data.
NSImageRep.hCreates and returns an array of image representation objects initialized using the contents of the specified file.
+ (NSArray *)imageRepsWithContentsOfFile:(NSString *)filename
A full or relative pathname specifying the file to open. This string should include the filename extension.
An array of image representation objects. The array contains one object for each image in the specified file.
If sent to the NSImageRep class object, this method returns an array of objects (all newly allocated instances of a subclass of NSImageRep, chosen through the use of imageRepClassForFileType:) that have been initialized with the contents of the file. If sent to a subclass of NSImageRep that recognizes the file type, this method returns an array of objects (all instances of that subclass) that have been initialized with the contents of the file.
This method returns nil in any of the following cases:
The message is sent to the NSImageRep class object and there are no subclasses in the NSImageRep class registry that handle the data in the file.
The message is sent to a subclass of NSImageRep and that subclass cannot handle the data in the file.
The NSImageRep subclass is unable to initialize itself with the contents of filename.
The NSImageRep subclass is initialized by creating an NSData object based on the contents of the file and passing it to the imageRepsWithData: method of the subclass. By default, the files handled include those with the extensions “tiff”, “gif”, “jpg”, “pict”, “pdf”, and “eps”.
NSImageRep.h
Creates and returns an array of image representation objects initialized using the contents of the specified URL.
+ (NSArray *)imageRepsWithContentsOfURL:(NSURL *)aURL
The URL pointing to the image data.
An array of image representation objects. The array contains one object for each image in the data at the specified URL.
If sent to the NSImageRep class object, this method returns an array of objects (all newly allocated instances of a subclass of NSImageRep) that have been initialized with the contents of the specified URL. If sent to a subclass of NSImageRep that recognizes the data at the specified URL, it returns an array of objects (all instances of that subclass) that have been initialized with the contents of that URL.
This method returns nil in any of the following cases:
The message is sent to the NSImageRep class object and there are no subclasses in the NSImageRep class registry that handle data in the specified URL.
The message is sent to a subclass of NSImageRep and that subclass cannot handle data in the specified URL.
The NSImageRep subclass is unable to initialize itself with the contents of the specified URL.
The NSImageRep subclass is initialized by creating an NSData object based on the contents of the specified URL and passing it to the imageRepsWithData: method.
NSImageRep.hCreates and returns an array of image representation objects initialized using the contents of the pasteboard.
+ (NSArray *)imageRepsWithPasteboard:(NSPasteboard *)pasteboard
The pasteboard containing the image data.
An array of image representation objects. The array contains one object for each image in the specified pasteboard.
If sent to the NSImageRep class object, this method returns an array of objects (all newly-allocated instances of a subclass of NSImageRep) that have been initialized with the data in the specified pasteboard. If sent to a subclass of NSImageRep that recognizes the pasteboard data, it returns an array of objects (all instances of that subclass) initialized with the pasteboard data.
This method returns nil in any of the following cases:
The message is sent to the NSImageRep class object and there are no subclasses in the NSImageRep class registry that handle the pasteboard data.
The message is sent to a subclass of NSImageRep and that subclass cannot handle the pasteboard data.
The NSImageRep subclass is unable to initialize itself with the contents the pasteboard.
The NSImageRep subclass is initialized by creating an NSData object based on the data in pasteboard and passing it to the imageRepsWithData: method.
NSImageRep.hCreates and returns an image representation object using the contents of the specified file.
+ (id)imageRepWithContentsOfFile:(NSString *)filename
A full or relative pathname specifying the file to open. This string should include the filename extension.
An initialized instance of an NSImageRep subclass, or nil if the image data could not be read.
If sent to the NSImageRep class object, this method returns a newly allocated instance of a subclass of NSImageRep (chosen through the use of imageRepClassForFileType:) initialized with the contents of the specified file. If sent to a subclass of NSImageRep that recognizes the type of data in the file, it returns an instance of that subclass initialized with the contents of the file.
This method returns nil in any of the following cases:
The message is sent to the NSImageRep class object and there are no subclasses in the NSImageRep class registry that handle the type of data in the specified file.
The message is sent to a subclass of NSImageRep and that subclass cannot handle the type of data in the specified file.
The NSImageRep subclass is unable to initialize itself with the contents of the specified file.
The NSImageRep subclass is initialized by creating an NSData object based on the contents of the file and passing it to the imageRepWithData: method. By default, the files handled include those with the extensions “tiff”, “gif”, “jpg”, “pict”, “pdf”, and “eps”.
NSImageRep.h
Creates and returns an image representation object using the data at the specified URL
+ (id)imageRepWithContentsOfURL:(NSURL *)aURL
The URL pointing to the image data.
An initialized instance of an NSImageRep subclass, or nil if the image data could not be read.
If sent to the NSImageRep class object, this method returns a newly allocated instance of a subclass of NSImageRep initialized with the contents of the specified URL. If sent to a subclass of NSImageRep that recognizes the data contained in the URL, it returns an instance of that subclass initialized with the data in the URL.
This method returns nil in any of the following cases:
The message is sent to the NSImageRep class object and there are no subclasses in the NSImageRep class registry that handle the data contained in the specified URL.
The message is sent to a subclass of NSImageRep and that subclass cannot handle the data contained in the specified URL.
The NSImageRep subclass is unable to initialize itself with the contents of the specified URL.
The NSImageRep subclass is initialized by creating an NSData object based on the contents of the file, then passing it to the imageRepWithData: method.
NSImageRep.hCreates and returns an image representation object using the contents of the specified pasteboard.
+ (id)imageRepWithPasteboard:(NSPasteboard *)pasteboard
The pasteboard containing the image data.
An initialized instance of an NSImageRep subclass, or nil if the image data could not be read.
If sent to the NSImageRep class object, this method returns a newly allocated instance of a subclass of NSImageRep initialized with the data in the specified pasteboard. If sent to a subclass of NSImageRep that recognizes the data on the pasteboard, it returns an instance of that subclass initialized with that data.
This method returns nil in any of the following cases:
The message is sent to the NSImageRep class object and there are no subclasses in the NSImageRep class registry that handle data of the type contained in the specified pasteboard.
The message is sent to a subclass of NSImageRep and that subclass cannot handle data of the type contained in the specified pasteboard.
The NSImageRep subclass is unable to initialize itself with the contents of the pasteboard.
The NSImageRep subclass is initialized by creating an NSData object based on the data the specified pasteboard and passing it to the imageRepWithData: method.
NSImageRep.hReturns an array of UTI strings identifying the image types supported by the receiver, either directly or through a user-installed filter service.
+ (NSArray *)imageTypes
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.
The returned list includes UTIs all file types supported by this image representation object plus those that can be opened by this image representation after being converted by a user-installed filter service. You can use the returned UTI strings with any method that supports UTIs.
NSImageRep.hReturns the list of file types supported directly by the receiver.
+ (NSArray *)imageUnfilteredFileTypes
An array of NSString objects. This array is empty by default. Subclasses must override to return the list of file formats they support.
The returned file types can include encoded HFS file types as well as filename extensions. When creating a subclass of NSImageRep, override this method to return a list of strings representing the supported file types. For example, the NSBitmapImageRep class implements code similar to the following for this method:
+ (NSArray *)imageUnfilteredFileTypes { |
static NSArray *types = nil; |
if (!types) types = [[NSArray alloc] |
initWithObjects:@"tiff", @"gif", @"jpg", @"bmp", nil]; |
return types; |
} |
If your subclass supports the types supported by its superclass, you must explicitly get the array of types from the superclass and put them in the array returned by this method.
+ imageFileTypes+ imageUnfilteredFileTypes (NSImage)NSImageRep.hReturns the list of pasteboard types supported directly by the receiver.
+ (NSArray *)imageUnfilteredPasteboardTypes
An array of NSString objects. This array is empty by default. Subclasses must override to return the list of pasteboard formats they support.
When creating a subclass of NSImageRep, override this method to return a list representing the supported pasteboard types. For example, the NSBitmapImageRep class implements code similar to the following for this method:
+ (NSArray *)imageUnfilteredPasteboardTypes { |
static NSArray *types = nil; |
if (!types) types = [[NSArray alloc] initWithObjects:NSTIFFPboardType, nil]; |
return types; |
} |
If your subclass supports the types supported by its superclass, you must explicitly get the list of types from the superclass and add them to the array returned by this method.
NSImageRep.hReturns an array of UTI strings identifying the image types supported directly by the receiver.
+ (NSArray *)imageUnfilteredTypes
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.
The returned list includes UTI strings only for those file types that are supported directly by the receiver. 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.
NSImageRep.hReturns an array containing the registered NSImageRep classes.
+ (NSArray *)registeredImageRepClasses
An array of Class objects identifying the registered NSImageRep subclasses.
NSImageRep.hAdds the specified class to the registry of available NSImageRep subclasses.
+ (void)registerImageRepClass:(Class)imageRepClass
The Class object for an NSImageRep subclass.
This method posts an NSImageRepRegistryDidChangeNotification, along with the receiving object, to the default notification center.
A good place to add image representation classes to the registry is in the load class method.
+ unregisterImageRepClass:load (NSObject)NSImageRep.hRemoves the specified NSImageRep subclass from the registry of available image representations.
+ (void)unregisterImageRepClass:(Class)imageRepClass
The Class object for an NSImageRep subclass.
This method posts the NSImageRepRegistryDidChangeNotification, along with the receiving object, to the default notification center.
NSImageRep.hReturns the number of bits per sample in the receiver.
- (NSInteger)bitsPerSample
The number of bits used to specify each component of data in a single pixel (for example, a value of 8 for an RGBA image means that each pixel is comprised of four 8-bit values). May also return NSImageRepMatchesDevice.
If the receiver is a planar image, this method returns the number of bits per sample per plane.
– setBitsPerSample:– bitsPerPixel (NSBitmapImageRep)– samplesPerPixel (NSBitmapImageRep)– isPlanar (NSBitmapImageRep)NSImageRep.hReturns a CGImage capturing the drawing of the receiver.
- (CGImageRef)CGImageForProposedRect:(NSRect *)proposedDestRect context:(NSGraphicsContext *)context hints:(NSDictionary *)hints
On input, the proposed destination rectangle for drawing the image. If NULL, it defaults to the smallest pixel-integral rectangle containing {{0,0}, [self size]}. The proposedDestRect is in user space in the reference context.
On output the proposedDestRect may have been altered. This is because a CGImage is necessarily pixel-integral, while an NSImage is not. In order to produce a CGImage for rect (0.5, 0.5, 4.0, 4.0) without distortion or double-antialiasing, we may have to produce a 5x5 CGImage, and also inflate the proposedDestRect. Drawing the CGImage in the out-value proposedDestRect is the same as drawing the NSImage in the in-value of proposed rect.
A graphics context., Can be NULL.
An optional dictionary of hints that provide more context for selecting or generating the image. See Image_Hint_Dictionary_Keys for a summary of the possible key-value pairs.
A CGImageRef. This may be an existing CGImage if one is available. If not, a new CGImage is created.
An NSImage is potentially resolution independent, and may have representations that allow it to draw well in many contexts. A CGImage is more like a single pixel-based representation. This method produces a snapshot of how the NSImage would draw if it was asked to draw in the proposed rectangle in the graphics context.
All input parameters are optional. They provide hints for how to choose among existing CGImages, or how to create one if there isn't already a CGImage available. The parameters are only hints.
This method is intended as an override point for image rep subclasses that naturally have a CGImage available. For example, NSBitmapImageRep overrides it to return the CGImage that naturally backs the rep. You don't need to override the method except possibly for performance, though. The NSImageRep-level implementation will produce a CGImage by making a buffer and calling [self draw]. That's likely to be the best possible implementation for reps that aren't naturally CGImage backed. The draw remains the only method of NSImageRep that a subclasser really needs to override.
NSImageRep.h
Returns the name of the receiver's color space.
- (NSString *)colorSpaceName
The colorspace name, or NSCalibratedRGBColorSpace if no name has been assigned.
NSImageRep.hImplemented by subclasses to draw the image in the current coordinate system.
- (BOOL)draw
YES if the image was successfully drawn; otherwise, NO if there was a problem. The default version of this method simply returns YES.
Subclass override this method to draw the image using the image data. By the time this method is called, the graphics state is already configured for you to draw the image at location (0.0, 0.0) in the current coordinate system.
The standard Application Kit subclasses all draw the image using the NSCompositeCopy composite operation defined in the “Constants” section of NSImage. Using the copy operator, the image data overwrites the destination without any blending effects. Transparent (alpha) regions in the source image appear black. To use other composite operations, you must place the representation into an NSImage object and use its drawAtPoint:fromRect:operation:fraction: or drawInRect:fromRect:operation:fraction: methods.
NSImageRep.h
Draws the receiver's image data at the specified point in the current coordinate system.
- (BOOL)drawAtPoint:(NSPoint)aPoint
The point in the current coordinate system at which to draw the image.
YES if the image was successfully drawn; otherwise, NO. If the size of the image has not yet been set, this method returns NO immediately
This method sets the origin of the current coordinate system to the specified point and then invokes the receiver’s draw method to draw the image at that point. Upon completion, it restores the current coordinates to their original setting. If aPoint is (0.0, 0.0), this method simply invokes the draw method.
NSImageRep.h
Draws the image, scaling it (as needed) to fit the specified rectangle.
- (BOOL)drawInRect:(NSRect)rect
The rectangle in the current coordinate system in which to draw the image.
YES if the image was successfully drawn; otherwise, NO. If the size of the image has not yet been set, this method returns NO immediately
This method sets the origin of the current coordinate system to the origin of the specified rectangle before invoking the receiver's draw method. If the rectangle size is different from the image's native size, this method adjusts the coordinate transform, causing the image to be scaled appropriately. After the draw method returns, the coordinate system changes are undone, restoring the original graphics state.
NSImageRep.hDraws all or part of the image in the specified rectangle in the current coordinate system.
- (BOOL)drawInRect:(NSRect)dstSpacePortionRect fromRect:(NSRect)srcSpacePortionRect operation:(NSCompositingOperation)op fraction:(CGFloat)requestedAlpha respectFlipped:(BOOL)respectContextIsFlipped hints:(NSDictionary *)hints
The rectangle in which to draw the image, specified in the current coordinate system.
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.
The compositing operation to use when drawing the image. See the NSCompositingOperation constants.
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.
YES if the flipped context of the receiver should be respected, otherwise NO.
An optional dictionary of hints that provide more context for selecting or generating the image. See Image_Hint_Dictionary_Keys for a summary of the possible key-value pairs.
YES if the image was successfully drawn; otherwise, NO.
If the srcSpacePortionRect and dstSpacePortionRect rectangles have different sizes, the source portion of the image is scaled to fit the specified destination rectangle.
NSImageRep.hReturns a Boolean value indicating whether the receiver has an alpha channel.
- (BOOL)hasAlpha
YES if the receiver has a known alpha channel; otherwise, NO.
NSImageRep.hReturns a Boolean value indicating whether the receiver is opaque.
- (BOOL)isOpaque
YES if the receiver is opaque; otherwise, NO.
Use this method to test whether an image representation completely covers the area within the rectangle returned by the size method.
The returned value does not indicate whether the image has an alpha channel or if there is partial or complete transparency when drawing the image rep. Use the hasAlpha method to determine if the image has an alpha channel.
NSImageRep.h
Returns the height of the image, measured in pixels.
- (NSInteger)pixelsHigh
The height of the image, measured in the units of the device coordinate space. This value is usually derived from the image data itself.
NSImageRep.h
Returns the width of the image, measured in pixels.
- (NSInteger)pixelsWide
The width of the image, measured in the units of the device coordinate space. This value is usually derived from the image data itself.
NSImageRep.hInforms the receiver that its image data has an alpha component.
- (void)setAlpha:(BOOL)flag
YES if you want the receiver to have an alpha component; otherwise NO.
Subclasses should call this method when loading image data to notify the parent class whether that data contains an alpha component. Passing in a value of YES does not add an alpha channel to the image data itself; it merely records the fact that the data has an alpha channel.
NSImageRep.h
Informs the receiver that its image data has the specified number of bits for each component of a pixel.
- (void)setBitsPerSample:(NSInteger)anInt
The number of bits used by each component of a pixel, or NSImageRepMatchesDevice.
Subclasses should call this method when loading image data to notify the parent class of how many bits each sample uses. Specifying a value that differs from the actual image data does not change the bit depth of the image.
NSImageRep.h
Informs the receiver of the color space used by the image data.
- (void)setColorSpaceName:(NSString *)string
The name of the color space used by the image data.
By default, an NSImageRep object’s color space name is NSCalibratedRGBColorSpace. Color space names are defined as part of the NSColor class, in NSGraphics.h. The following are valid color space names:
NSImageRep.h
Sets whether the receiver's image is opaque.
- (void)setOpaque:(BOOL)flag
YES if the image should be treated as fully opaque; otherwise, NO to indicate the image may include some transparent regions.
NSImageRep.h
Informs the receiver of the image data height.
- (void)setPixelsHigh:(NSInteger)anInt
The height of the image, measured in pixels.
Subclasses should call this method when loading image data to notify the parent class of the image height. You cannot use this method to change the actual number of pixels in the image.
NSImageRep.h
Informs the receiver of the image data width.
- (void)setPixelsWide:(NSInteger)anInt
The width of the image, measured in pixels.
Subclasses should call this method when loading image data to notify the parent class of the image width. You cannot use this method to change the actual number of pixels in the image.
NSImageRep.hSets the size of the image representation to the specified value.
- (void)setSize:(NSSize)aSize
The new size of the image representation, measured in points in the user coordinate space.
This method determines the size of the image when it’s rendered. It is not necessarily the same as the width and height of the image in pixels as specified by the image data, nor must it be equal to the size set for the NSImage object that wraps this image representation. You must set the image size before you can render it.
The size of an image representation combined with the physical dimensions of the image data determine the resolution of the image.
NSImageRep.hReturns the size of the image representation.
- (NSSize)size
The size of the image representation, measured in points in the user coordinate space.
This size is the size of the image representation when it’s rendered. It is not necessarily the same as the width and height of the image in pixels as specified by the image data, nor must it be equal to the size set for the NSImage object that wraps this image representation.
The size of an image representation combined with the physical dimensions of the image data determine the resolution of the image.
NSImageRep.hThe following constant is used by NSImageRep to denote an attribute whose value changes to match the display device.
enum {
NSImageRepMatchesDevice
};
NSImageRepMatchesDeviceIndicates that the value of certain attributes, such as the number of colors or bits per sample, will change to match the display device.
This value can be passed in (or received back) as the value of bitsPerSample, pixelsWide, and pixelsHigh.
Available in Mac OS X v10.0 and later.
Declared in NSImageRep.h.
The following constant maps to the new notification and is for legacy code only.
#define NSImageRepRegistryChangedNotification NSImageRepRegistryDidChangeNotification
NSImageRepRegistryChangedNotificationAn older name for the NSImageRepRegistryDidChangeNotification notification. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSImageRep.h.
Posted whenever the NSImageRep class registry changes.
The notification object is the image class that is registered or unregistered. This notification does not contain a userInfo dictionary.
NSImageRep.h
Last updated: 2009-07-06
