Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

NXImageRep

	Inherits From:	Object
	Declared In:	appkit/NXImageRep.h

Class Description

NXImageRep is an abstract superclass; each of its subclasses knows how to draw an image from a particular kind of source data.  While an NXImageRep subclass can be used directly, it's typically used through an NXImage object.  An NXImage manages a group of representations, choosing the best one for the current output device. There are four subclasses defined in the Application Kit:

	Subclass	Source Data
	NXBitmapImageRep	Tag Image File Format (TIFF) and other bitmap data
	NXEPSImageRep	Encapsulated PostScript code (EPS)
	NXCustomImageRep	A delegated method that can draw the image
	NXCachedImageRep	A rendered image, usually in an off-screen window

Another subclass, N3DRIBImageRep, is defined in the 3D Graphics Kit.  It renders an image from RenderMan Interface Bytestream (RIB) data.  In applications that use the 3D Kit, NXImage will automatically use N3DRIBImageRep to handle RIB data. You can define other NXImageRep subclasses for objects that render images from other types of source information.  You make a subclass known to NXImage by invoking its registerImageRep: class method.  The NXImageRep subclass informs NXImage of the data types it can support through its imageUnfilteredFileTypes,  imageUnfilteredPasteboardTypes, and canLoadFromStream: class methods.  Once an NXImageRep subclass is registered with NXImage, an instance of that subclass is created anytime NXImage encounters the type of data handled by that subclass.

Instance Variables

NXSize size;

size

The size of the image in screen pixels.

Method Types

	Initializing	initFromPasteboard:
	Checking data types	+ canInitFromPasteboard:

+ canLoadFromStream: + imageFileTypes + imagePasteboardTypes + imageUnfilteredFileTypes + imageUnfilteredPasteboardTypes

Setting the size of the image

setSize:

getSize:

Representation attributes

setNumColors:

numColors setAlpha: hasAlpha setBitsPerSample: bitsPerSample setPixelsHigh: pixelsHigh setPixelsWide: pixelsWide setOpaque: isOpaque

Drawing the image

draw

drawAt: drawIn:

Archiving

read:

write:

Class Methods

canInitFromPasteboard:

+ (BOOL)canInitFromPasteboard:(Pasteboard *)pasteboard

Returns YES if NXImageRep can handle the data represented by pasteboard.  By default, this method returns 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 NXImageRep that accepts image data from a nondefault pasteboard type, you override the imageUnfilteredPasteboardTypes method to assure that this method returns the correct response. See also:  + imageUnfilteredPasteboardTypes

canLoadFromStream:

+ (BOOL)canLoadFromStream:(NXStream *)stream

Tests whether the receiving class can initialize an instance of itself from stream.  Returns NO by default. Override this method when you create a subclass of NXImageRep that can initialize itself from data in an NXStream.  Your method should be able to seek in stream to determine whether it contains valid data for creating an instance of the class.  It should return YES if there's a good chance that stream contains data of the type handled by the NXImageRep subclass.  It should return NO only if it is clear from examining stream that there is no data that the NXImageRep subclass can handle.  The determination should be able to be made by looking at the first few characters in stream.  Before returning, your method should return the stream pointer to its initial position.

imageFileTypes

+ (const char *const *)imageFileTypes

Returns a null-terminated array of strings representing all file types supported by NXImageRep.  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.  Don't override this method when subclassing NXImageRep: it always returns a valid list for a subclass of NXImageRep that correctly overrides the imageUnfilteredFileTypes method. By default, the returned array is empty. See also:  + imageUnfilteredFileTypes

imagePasteboardTypes

+ (const NXAtom *)imagePasteboardTypes

Returns a null-terminated array representing all pasteboard types supported by NXImageRep or one of its subclasses.  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 NXImageRep; it always return a valid list for a subclass of NXImageRep that correctly overrides the imageUnfilteredPasteboardTypes method. By default, the returned array is empty. See also:  + imageUnfilteredPasteboardTypes

imageUnfilteredFileTypes

+ (const char *const *)imageUnfilteredFileTypes

Returns a null-terminated array of strings representing all file types (extensions) supported by the NXImageRep.  By default, the returned array is emtpy. When creating a subclass of NXImageRep, override this method to return a list of strings representing the file types supported. For example, NXBitmapImageRep implements the following code for this method:

+ (const char *const *)imageUnfilteredFileTypes
{
static const char *const types[] = {"tiff", "tif", NULL};
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. See also:  + imageFileTypes, + imageRepForFileType: (NXImage)

imageUnfilteredPasteboardTypes

+ (const NXAtom *)imageUnfilteredPasteboardTypes

Returns a null-terminated array representing all pasteboard types supported by the NXImageRep.  By default, the returned array is empty. When creating a subclass of NXImageRep, override this method to return a list representing the pasteboard types supported. For example, NXBitmapImageRep implements the following code for this method:

+ (const NXAtom *)imageUnfilteredPasteboardTypes
{
static NXAtom tiffTypes[2]={0, NULL};
if (!tiffTypes[0]) tiffTypes[0] = NXTIFFPboardType;
return tiffTypes;
}

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, + imageRepForPasteboardType: (NXImage)

Instance Methods

bitsPerSample

(int)bitsPerSample

Returns the number of bits used to specify a single pixel in each component of the data.  If the image isn't specified by pixel values, but is device-independent, the return value will be NX_MATCHESDEVICE. See also:  setBitsPerSample:

draw

(BOOL)draw

Implemented by subclasses to draw the image at location (0.0, 0.0) in the current coordinate system.  Subclass methods return YES if the image is successfully drawn, and NO if it isn't.  This version of the method simply returns YES. See also:  drawAt:, drawIn:

drawAt:

(BOOL)drawAt:(const NXPoint *)point

Translates the current coordinate system to the location specified by point and has the receiver's draw method draw the image at that point. This method returns NO without translating 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. The coordinate system is not restored after it has been translated. See also:  draw, drawIn:

drawIn:

(BOOL)drawIn:(const NXRect *)rect

Draws the image so that it fits inside the rectangle referred to by rect.  The current coordinate system is first translated to the point specified in the rectangle and is then scaled so the image will fit within the rectangle.  The receiver's draw method is then invoked to draw the image. This method returns NO 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. The previous coordinate system is not restored after it has been altered. See also:  draw, drawAt:

getSize:

getSize:(NXSize *)theSize

Copies the size of the image to the structure referred to by theSize, and returns self.  The size is provided in units of the base coordinate system. See also:  setSize:

hasAlpha

(BOOL)hasAlpha

Returns YES if the receiver has been informed that the image has a coverage component (alpha), and NO if not. See also:  setAlpha:

initFromPasteboard:

initFromPasteboard:(Pasteboard *)pasteboard

Initializes the NXImageRep with data from the given pasteboard.

isOpaque

(BOOL)isOpaque

Returns YES if the receiver is opaque; NO otherwise.  Use this method to test whether an NXImageRep completely covers the area within the rectangle returned by getSize:.  Use the method setOpaque: to set the value returned by this method. See also:  hasAlpha, getSize:, setOpaque:

numColors

(int)numColors

Returns the number of color components in the image.  For example, the return value will be 4 for images specified by cyan, magenta, yellow, and black (CMYK) or any other four components.  It will be 3 for images specified by red, green, and blue (RGB),  hue, saturation, and brightness (HSB), or any other three components.  And it will be 1 for images that use only a gray scale.  NX_MATCHESDEVICE is a meaningful return value for representations that vary their drawing depending on the output device. See also:  setNumColors:

pixelsHigh

(int)pixelsHigh

Returns the height of the image in pixels, as specified in the image data.  If the image isn't specified by pixel values, but is device-independent, the return value will be NX_MATCHESDEVICE. See also:  setPixelsHigh:

pixelsWide

(int)pixelsWide

Returns the width of the image in pixels, as specified in the image data.  If the image isn't specified by pixel values, but is device-independent, the return value will be NX_MATCHESDEVICE. See also:  setPixelsWide:

read:

read:(NXTypedStream *)stream

Reads the NXImageRep from the typed stream stream. See also:  write:

setAlpha:

setAlpha:(BOOL)flag

Informs the NXImageRep whether the image has an alpha component.  flag should be YES if it does, and NO if it doesn't. Returns self. See also:  hasAlpha

setBitsPerSample:

setBitsPerSample:(int)anInt

Informs the NXImageRep that the image has anInt bits of data for each pixel in each component.  If the image isn't specified by pixel values, but is device-independent, anInt should be NX_MATCHESDEVICE.  Returns self. See also:  bitsPerSample

setNumColors:

setNumColors:(int)anInt

Informs the NXImageRep that the image has anInt number of color components.  For color images with cyan, magenta, yellow, and black (CMYK) components, anInt should be 4, for color images with red, green, and blue (RGB) components, it should be 3, and for images that use only a gray scale, it should be 1.  The alpha component is not included.  NX_MATCHESDEVICE could be a meaningful value, if the representation varies its drawing depending on the output device.  Returns self. See also:  numColors

setOpaque:

setOpaque:(BOOL)flag

Sets opacity of the NXImageRep's image.

setPixelsHigh:

setPixelsHigh:(int)anInt

Informs the NXImageRep that the data specifies an image anInt pixels high.  If the image isn't specified by pixel values, but is device-independent, anInt should be NX_MATCHESDEVICE.  Returns self. See also:  pixelsHigh

setPixelsWide:

setPixelsWide:(int)anInt

Informs the NXImageRep that the data specifies an image anInt pixels wide.  If the image isn't specified by pixel values, but is device-independent, anInt should be NX_MATCHESDEVICE.  Returns self. See also:  pixelsWide

setSize:

setSize:(const NXSize *)aSize

Sets the size of the image in units of the base coordinate system, and returns self.  This 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. See also:  getSize:

write:

write:(NXTypedStream *)stream

Writes the NXImageRep to the typed stream stream. See also:  read: