---

NSImageRep

Overview

NSImageRep 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’s typically used through an NSImage object. An NSImage manages a group of representations, choosing the best one for the current output device.

Tasks

Constructors

• NSImageRep

Creating an NSImageRep

• imageRepsWithContentsOfFile
• imageRepsWithPasteboard
• imageRepsWithContentsOfURL
• imageRepWithContentsOfFile
• imageRepWithPasteboard
• imageRepWithContentsOfURL

Checking Data Types

• canInitWithData
• canInitWithPasteboard
• imageFileTypes
• imagePasteboardTypes
• imageUnfilteredFileTypes
• imageUnfilteredPasteboardTypes

Setting the Size of the Image

• setSize
• size

Specifying Information About the Representation

• bitsPerSample
• colorSpaceName
• hasAlpha
• isOpaque
• pixelsHigh
• pixelsWide
• setAlpha
• setBitsPerSample
• setColorSpaceName
• setOpaque
• setPixelsHigh
• setPixelsWide

Drawing the Image

• draw
• drawAtPoint
• drawInRect

Managing NSImageRep Subclasses

• imageRepClassForData
• imageRepClassForFileType
• imageRepClassForPasteboardType
• registeredImageRepClasses
• registerImageRepClass
• unregisterImageRepClass

Static Methods

canInitWithData

Should be overridden in subclasses to return true if the receiver can initialize itself from data, and false if it cannot.

public static boolean canInitWithData(NSData data)

Discussion

Note that this method doesn’t need to do a comprehensive check; it should return false only if it knows the receiver can’t initialize itself from data.

See Also

• canInitWithPasteboard

canInitWithPasteboard

Returns true if the NSImageRep can handle the data represented by pasteboard, otherwise returns false.

public static boolean canInitWithPasteboard(NSPasteboard pasteboard)

Discussion

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 true. 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.

See Also

• canInitWithData

imageFileTypes

Returns an array of Strings representing all file types supported by NSImageRep or one of its subclasses.

public static NSArray imageFileTypes()

Discussion

The list includes both those types returned by the imageUnfilteredFileTypes class method and those that can be converted to a supported type by a user-installed filter service. The file types returned 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.

imagePasteboardTypes

Returns an array of Strings representing all pasteboard types supported by NSImageRep or one of its subclasses.

public static NSArray imagePasteboardTypes()

Discussion

The list includes both those types returned by the imageUnfilteredPasteboardTypes class method and those that can be converted by a user-installed filter service to a supported type. 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.

imageRepClassForData

Returns the NSImageRep subclass that handles data of type data, or null if the NSImage class registry contains no subclasses that handle data of the specified type.

public static Class imageRepClassForData(NSData data)

imageRepClassForFileType

Returns the NSImageRep subclass that handles files of type type, or null if the NSImage class registry contains no subclasses that handle files of the specified type.

public static Class imageRepClassForFileType(String type)

Discussion

type may be either an encoded HFS file type or a filename extension.

imageRepClassForPasteboardType

Returns the NSImageRep subclass that handles pasteboard data of type type, or null if the NSImage class registry contains no subclasses that handle pasteboard data of the specified type.

public static Class imageRepClassForPasteboardType(String type)

imageRepsWithContentsOfFile

public static NSArray imageRepsWithContentsOfFile(String filename)

Discussion

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 filename. If sent to a subclass of NSImageRep that recognizes the type of file specified by filename, it returns an array of objects (all instances of that subclass) that have been initialized with the contents of the file filename.

The imageRepsWithContentsOfFile method returns null 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 indicated by filename.

• The message is sent to a subclass of NSImageRep, and that subclass doesn’t handle data of the type indicated by filename.

• The NSImageRep subclass is unable to initialize itself with the contents of filename.

The filename argument may be a full or relative pathname and should include an extension that identifies the data type in the file. By default, the files handled include those with the extensions “tiff”, “gif”, “jpg”, “pict”, “pdf”, and “eps”.

The NSImageRep subclass is initialized by creating an NSData object based on the contents of the file, then passing it to imageRepsWithData.

See Also

• imageFileTypes

imageRepsWithContentsOfURL

public static NSArray imageRepsWithContentsOfURL(java.net.URL aURL)

Discussion

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 aURL. If sent to a subclass of NSImageRep that recognizes the type of data contained in aURL, it returns an array of objects (all instances of that subclass) that have been initialized with the contents of aURL.

The imageRepsWithContentsOfURL method returns null 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 aURL.

• The message is sent to a subclass of NSImageRep, and that subclass doesn’t handle data of the type contained in aURL.

• The NSImageRep subclass is unable to initialize itself with the contents of aURL.

The NSImageRep subclass is initialized by creating an NSData object based on the contents of aURL, then passing it to imageRepsWithData.

imageRepsWithPasteboard

public static NSArray imageRepsWithPasteboard(NSPasteboard pasteboard)

Discussion

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 pasteboard. If sent to a subclass of NSImageRep that recognizes the type of data contained in pasteboard, it returns an array of objects (all instances of that subclass) initialized with the data in pasteboard.

imageRepsWithPasteboard returns null 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 pasteboard.

• The message is sent to a subclass of NSImageRep, and that subclass doesn’t handle data of the type contained in pasteboard.

• The NSImageRep subclass is unable to initialize itself with the contents of pasteboard.

The NSImageRep subclass is initialized by creating an NSData object based on the data in pasteboard, then passing it to imageRepsWithData.

See Also

• imagePasteboardTypes

imageRepWithContentsOfFile

public static NSImageRep imageRepWithContentsOfFile(String filename)

Discussion

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 file filename. If sent to a subclass of NSImageRep that recognizes the type of file specified by filename, it returns an instance of that subclass initialized with the contents of the file filename.

The imageRepWithContentsOfFile method returns null 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 indicated by filename.

• The message is sent to a subclass of NSImageRep, and that subclass doesn’t handle data of the type indicated by filename.

• The NSImageRep subclass is unable to initialize itself with the contents of filename.

The filename argument may be a full or relative pathname and should include an extension that identifies the data type in the file. By default, the files handled include those with the extensions “tiff”, “gif”, “jpg”, “pict”, “pdf”, and “eps”.

The NSImageRep subclass is initialized by creating an NSData object based on the contents of the file, then passing it to imageRepWithData.

See Also

• imageFileTypes

imageRepWithContentsOfURL

public static Object imageRepWithContentsOfURL(java.net.URL aURL)

Discussion

If sent to the NSImageRep class object, this method returns a newly allocated instance of a subclass of NSImageRep initialized with the contents of aURL. If sent to a subclass of NSImageRep that recognizes the type of data contained in aURL, it returns an instance of that subclass initialized with the contents of aURL.

The imageRepWithContentsOfURL method returns null 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 aURL.

• The message is sent to a subclass of NSImageRep, and that subclass doesn’t handle data of the type contained in aURL.

• The NSImageRep subclass is unable to initialize itself with the contents of aURL.

The NSImageRep subclass is initialized by creating an NSData object based on the contents of the file, then passing it to imageRepWithData.

imageRepWithPasteboard

public static NSImageRep imageRepWithPasteboard(NSPasteboard pasteboard)

Discussion

If sent to the NSImageRep class object, this method returns a newly allocated instance of a subclass of NSImageRep initialized with the data in pasteboard. If sent to a subclass of NSImageRep that recognizes the type of data contained in pasteboard, it returns an instance of that subclass initialized with the data in pasteboard.

The imageRepWithPasteboard method returns null 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 pasteboard.

• The message is sent to a subclass of NSImageRep, and that subclass doesn’t handle data of the type contained in pasteboard.

• The NSImageRep subclass is unable to initialize itself with the contents of pasteboard.

The NSImageRep subclass is initialized by creating an NSData object based on the data in pasteboard, then passing it to imageRepWithData.

See Also

• imagePasteboardTypes

imageUnfilteredFileTypes

Returns an array of Strings representing all file types (extensions) supported by the NSImageRep.

public static NSArray imageUnfilteredFileTypes()

Discussion

The file types returned can include encoded HFS file types as well as filename extensions. By default, the returned array is empty.

When creating a subclass of NSImageRep, override this method to return a list of strings representing the supported file 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.

See Also

• imageFileTypes
• imageUnfilteredFileTypes (NSImage)

imageUnfilteredPasteboardTypes

Returns an array representing all pasteboard types supported by the NSImageRep.

public static NSArray imageUnfilteredPasteboardTypes()

Discussion

By default, the returned array is empty.

When creating a subclass of NSImageRep, override this method to return a list representing the supported pasteboard 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.

See Also

• imagePasteboardTypes
• imageUnfilteredPasteboardTypes (NSImage)

registeredImageRepClasses

Returns an array containing the registered NSImageRep classes.

public static NSArray registeredImageRepClasses()

registerImageRepClass

Adds imageRepClass to the registry of available NSImageRep classes.

public static void registerImageRepClass(Class imageRepClass)

Discussion

This method posts an ImageRepRegistryDidChangeNotification, along with the receiving object, to the default notification center.

See Also

• unregisterImageRepClass

unregisterImageRepClass

Removes imageRepClass from the registry of available NSImageRep classes.

public static void unregisterImageRepClass(Class imageRepClass)

Discussion

This method posts the ImageRepRegistryDidChangeNotification, along with the receiving object, to the default notification center.

See Also

• registerImageRepClass

Instance Methods

bitsPerSample

Returns the number of bits per sample—that is, the number of bits used to specify each component of data in a pixel. If the receiver is a planar image, this method returns the number of bits per sample per plane.

public int bitsPerSample()

See Also

• setBitsPerSample
• bitsPerPixel (NSBitmapImageRep)
• samplesPerPixel (NSBitmapImageRep)
• isPlanar (NSBitmapImageRep)

colorSpaceName

Returns the name if the image’s color space, or NSGraphics.CalibratedRGBColorSpace if no name has been assigned.

public String colorSpaceName()

See Also

• setColorSpaceName

draw

Implemented by subclasses to draw the image at location (0.0, 0.0) in the current coordinate system.

public boolean draw()

Discussion

Subclass methods return true if the image is successfully drawn, and false if it isn’t. This version of the method simply returns true.

The standard Application Kit subclasses all draw the image using the NSImage.CompositeCopy composite operation defined in NSImage’s “Constants” section. The image data overwrites the destination without any blending effects; any 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 or drawInRect methods.

drawAtPoint

Sets the current coordinates to aPoint, invokes the receiver’s draw method to draw the image at that point, then restores the current coordinates to their original setting.

public boolean drawAtPoint(NSPoint aPoint)

Discussion

If aPoint is (0.0, 0.0), drawAtPoint simply invokes draw.

This method returns false without translating, scaling, or drawing if the size of the image has not been set. Otherwise it returns the value returned by the draw method, which indicates whether the image is successfully drawn.

See Also

• setSize
• drawInRect

drawInRect

Draws the image so it fits inside rect.

public boolean drawInRect(NSRect rect)

Discussion

The current coordinates are set to the point specified in the rectangle and are scaled so the image will fit within the rectangle. The receiver’s draw method is then invoked to draw the image. After draw has been invoked, the current coordinates and scale factors are restored to their original settings.

This method returns false without translating, scaling, or drawing if the size of the image has not been set. Otherwise it returns the value returned by the draw method, which indicates whether the image is successfully drawn.

See Also

• setSize
• drawAtPoint

hasAlpha

Returns true if the receiver has been informed that the image has a coverage component (alpha), and false if not.

public boolean hasAlpha()

See Also

• setAlpha

isOpaque

Returns true if the receiver is opaque, false otherwise.

public boolean isOpaque()

Discussion

Use this method to test whether an NSImageRep completely covers the area within the rectangle returned by size.

This value does not indicate if the image has an alpha channel and if there is partial or complete transparency when drawing the image rep. Use hasAlpha to determine if the image has an alpha channel.

See Also

• setOpaque

pixelsHigh

Returns the height of the image in pixels, as specified in the image data.

public int pixelsHigh()

See Also

• setPixelsHigh
• pixelsWide
• size

pixelsWide

Returns the width of the image in pixels, as specified in the image data.

public int pixelsWide()

See Also

• setPixelsWide
• pixelsHigh
• size

setAlpha

Informs the receiver whether the image has an alpha component.

public void setAlpha(boolean flag)

Discussion

flag should be true if it does, and false if it doesn’t.

See Also

• hasAlpha

setBitsPerSample

Informs the receiver that the image has anInt bits of data for each pixel in each component.

public void setBitsPerSample(int anInt)

See Also

• bitsPerSample

setColorSpaceName

Informs the receiver of the image’s color space.

public void setColorSpaceName(String string)

Discussion

By default, an NSImageRep’s color space name is NSGraphics.CalibratedRGBColorSpace. Color space names are defined as part of the NSGraphics class. The following are valid color space names:

• NSGraphics.CalibratedWhiteColorSpace

• NSGraphics.CalibratedBlackColorSpace

• NSGraphics.CalibratedRGBColorSpace

• NSGraphics.DeviceWhiteColorSpace

• NSGraphics.DeviceBlackColorSpace

• NSGraphics.DeviceRGBColorSpace

• NSGraphics.DeviceCMYKColorSpace

• NSGraphics.NamedColorSpace

• NSGraphics.CustomColorSpace

See Also

• colorSpaceName

setOpaque

Sets opacity of the receiver’s image.

public void setOpaque(boolean flag)

Discussion

If flag is true, the image is opaque.

See Also

• isOpaque

setPixelsHigh

Informs the receiver that the data specifies an image anInt pixels high.

public void setPixelsHigh(int anInt)

See Also

• pixelsHigh
• setPixelsWide
• setSize

setPixelsWide

Informs the receiver that the data specifies an image anInt pixels wide.

public void setPixelsWide(int anInt)

See Also

• pixelsWide
• setPixelsHigh
• setSize

setSize

Sets the size of the image to aSize in units of the base coordinate system.

public void setSize(NSSize aSize)

Discussion

This method determines the size of the image when it’s rendered; it’s not necessarily the same as the width and height of the image in pixels as specified in the image data. You must set the image size before you can render it.

See Also

• size
• draw
• setPixelsHigh
• setPixelsWide

size

Returns the size of the image in units of the base coordinate system.

public NSSize size()

Discussion

This size is the size of the image when it’s rendered; it’s not necessarily the same as the width and height of the image in pixels as specified in the image data.

See Also

• setSize
• pixelsHigh
• pixelsWide

Constants

The following constant is defined as a convenience by NSImageRep:

Notifications

ImageRepRegistryDidChangeNotification

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.

---