Copyright ©1995 by NeXT Computer, Inc. All Rights Reserved.
| NXImage |
| Inherits From: | Object | |
| Declared In: | appkit/NXImage.h |
| Class Description |
| An NXImage object contains an image that can be composited anywhere without first being drawn in any particular View. It manages the image by: |
|
Reading image data from the application bundle, from a Pasteboard, or from an NXStream. | |
|
Choosing the representation that's appropriate for a particular data type. | |
|
Keeping multiple representations of the same image. | |
|
Choosing the representation that's appropriate for any given display device. | |
|
Caching the representations it uses by rendering them in off-screen windows. | |
|
Optionally retaining the data used to draw the representations, so that they can be reproduced when needed. | |
|
Compositing the image from the off-screen cache to where it's needed on-screen. | |
|
Reproducing the image for the printer so that it matches what's displayed on-screen, yet is the best representation possible for the printed page. | |
|
Automatically using any filtering services installed by the user to convert image data from unsupported formats to supported formats. |
| Defining an Image
An image can be created from various types of data: |
|
Encapsulated PostScript code (EPS) | |
|
Bitmap data in Tag Image File Format (TIFF) | |
|
Untagged (raw) bitmap data | |
|
RenderMan Interface Bytestream code (RIB) | |
|
Other image data supported by an NXImageRep subclass registered with the NXImage class | |
|
Data that can be filtered to a supported type by a user-installed filter service |
| If data is placed in a file (for example, in an application bundle), the NXImage object can access the data whenever it's needed to create the image. If data is read from a stream, the NXImage object may need to retain the data itself.
Images can also be defined by the program, in two ways: |
|
By drawing the image in an off-screen window maintained by the NXImage object. In this case, the NXImage maintains only the cached image. | |
|
By defining a method that can be used to draw the image when needed. This allows the NXImage to delegate responsibility for producing the image to some other object. |
| Image Representations
An NXImage 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 NXImage returns a List of its representations in response to a representationList message. Each representation is a kind of NXImageRep object: |
| NXEPSImageRep | An image that can be recreated from EPS data that's either retained by the object or at a known location in the file system. | |
| NXBitmapImageRep | An image that can be recreated from bitmap or TIFF data. | |
| N3DRIBImageRep | An image that can be recreated from RIB data. | |
| NXCustomImageRep | An image that can be redrawn by a method defined in the application. | |
| NXCachedImageRep | 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 NXImageRep subclasses for objects that render images from other types of source data. You make a subclass known to NXImage by invoking the registerImageRep: class method. NXImage determines the data types that each subclass can support by invoking its imageUnfilteredFileTypes and imageUnfilteredPasteboardTypes methods.
Choosing Representations The NXImage 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. |
| 1. | Choose a color representation for a color device, and a gray-scale representation for a monochrome device. | |
| 2. | Choose a representation with a resolution that matches the resolution of the device, or if no representation matches, choose the one with the highest resolution. | |
| By default, any image representation with a resolution that's an integer multiple of the device resolution is considered to match. If more than one representation matches, the NXImage will choose the one that's closest to the device resolution. However, you can force resolution matches to be exact by passing NO to the setMatchedOnMultipleResolution: method. | ||
| Rule 2 prefers TIFF and bitmap representations, which have a defined resolution, over EPS representations, which don't. However, you can use the setEPSUsedOnResolutionMismatch: method to have the NXImage choose an EPS representation in case a resolution match isn't possible. | ||
| 3. | If all else fails, choose the representation with a specified bits per sample that matches the depth of the device. If no representation matches, choose the one with the highest bits per sample. |
| By passing NO to the setColorMatchPreferred: method, you can have the NXImage 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 NXImage has two color TIFF representations with the same resolution and depth--the one that will be chosen is system dependent.
Caching Representations When first asked to composite the image, the NXImage 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 NXImage 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.
Image Size Before an NXImage 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 NXImage is provided with a representation, the size will be set from the data. The bounding box is used to determine the size of an NXEPS ImageRep. The TIFF fields "ImageLength" and "ImageWidth" are used to determine the size of an NXBitmapImageRep. The RiDisplay() parameters are used to determine the size of an N3DRIBImageRep.
Coordinate Systems Images have the horizontal and vertical orientation of the base coordinate system; they can't be rotated or 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.) It's possible to refer to portions of an image when compositing (or when defining subimages), 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.
Named Images An NXImage object can be identified either by its id or by a name. Assigning an NXImage a name adds it to a database kept by the class object; each name in the database identifies one and only one instance of the class. When you ask for an NXImage object by name (with the findImageNamed: 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 looking (for historical reasons) in the _ _ICON, _ _EPS, and _ _TIFF segments of the application's executable file, and then in the application bundle. If a section or file matches the name, an NXImage is created from the data stored there. You can therefore create NXImage objects simply by including EPS or TIFF data for them within the executable file, or in files inside the application's file package. The job of displaying an image within a View can be entrusted to a Cell object. A Cell identifies the image it's to display by the name of the NXImage object. The following code sets myCell to display one of the system bitmaps: |
id myCell = [[Cell alloc] initIconCell:"NXswitch"];
| Image Filtering Services
NXImage 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 a list of all file types from which NXImage can create an instance of itself. This list includes all file types supported by registered subclasses of NXImageRep, and those types that can be converted to supported file types through a user-installed filter service. |
| Instance Variables |
| char *name; |
| name | The name assigned to the image. |
| Method Types |
| Initializing a new NXImage instance |
 init |
| initSize: initFromSection: initFromFile: initFromStream: initFromPasteboard: initFromImage:rect: copyFromZone: |
| Freeing an NXImage object | free | |
| Setting the size of the image | setSize: |
| getSize: |
| Referring to images by name | setName: |
| name + findImageNamed: |
| Specifying the image | useDrawMethod:inObject: |
| useFromSection: useFromFile: loadFromFile: useRepresentation: useCacheWithDepth: loadFromStream: lockFocus lockFocusOn: unlockFocus |
| Using the image | composite:toPoint: |
| composite:fromRect:toPoint: dissolve:toPoint: dissolve:fromRect:toPoint: |
| Choosing which image representation to use |
| setColorMatchPreferred: |
| isColorMatchPreferred setEPSUsedOnResolutionMismatch: isEPSUsedOnResolutionMismatch setMatchedOnMultipleResolution: isMatchedOnMultipleResolution |
| Getting the representations | lastRepresentation |
| bestRepresentation representationList removeRepresentation: |
| Determining how the image is stored |
| setUnique: |
| isUnique setDataRetained: isDataRetained setCacheDepthBounded: isCacheDepthBounded getImage:rect: |
| Determining how the image is drawn |
| setFlipped: |
| isFlipped setScalable: isScalable setBackgroundColor: backgroundColor drawRepresentation:inRect: recache |
| Assigning a delegate | setDelegate: |
| delegate |
| Producing TIFF data for the image |
| writeTIFF: |
| writeTIFF:allRepresentations: writeTIFF:allRepresentations:usingCompression: |
| andFactor: |
| Managing NXImageRep subclasses |
| + registerImageRep: |
| + unregisterImageRep: + imageRepForFileType: + imageRepForPasteboardType: + imageRepForStream: + imageUnfilteredFileTypes + imageUnfilteredPasteboardTypes |
| Testing image data sources | + canInitFromPasteboard: |
| + imageFileTypes + imagePasteboardTypes |
| Archiving | read: |
| write: finishUnarchiving |
| Class Methods |
| canInitFromPasteboard: |
| + (BOOL)canInitFromPasteboard:(Pasteboard *)pasteboard |
| Tests whether NXImage can create an instance of itself from the data represented by pasteboard. Returns YES if NXImage's list of registered NXImageReps includes a class that can handle the data represented by pasteboard.
By default, this method returns YES if pasteboard's type is NXTIFFPboardType, NXPostScriptPboardType, or NXFilenamePboardType (for file names with extension ".tiff", ".tif", or ".eps"). Applications linked against libMedia_s.a also return YES if pasteboard's type is N3DRIBPboardType or NXFilenamePboardType (for file names with extension ".rib"). NXImage uses the NXImageRep class method imageUnfilteredPasteboardTypes to find the class that can handle the data in pasteboard. When creating a subclass of NXImageRep that accepts image data from a non-default pasteboard type, override the imageUnfilteredPasteboardTypes method to notify NXImage of the pasteboard types your class supports. See also: + imagePasteboardTypes, + imageRepForPasteboard:, + imageUnfilteredPasteboardTypes (NXImageRep), N3DRIBImageRep (3D Kit Classes) |
| findImageNamed: |
| + findImageNamed:(const char *)name |
| Returns the NXImage instance associated with name. The returned object can be: |
|
One that's been assigned a name with the setName: method, | |
|
One of the named system bitmaps provided by the Application Kit, or | |
|
One that's been created and named by this method. |
| If there's no known NXImage with name, this method tries to create one by searching for image data in the application's executable file and in the application bundle: |
| 1. | For historical reasons, it looks in the application executable. It looks first in the _ _ICON segment for a name section containing either Encapsulated PostScript code (EPS) or Tag Image File Format (TIFF) data. It looks next for a section with TIFF data in the _ _TIFF segment if name includes a ".tiff" extension, or for a section containing EPS data in the _ _EPS segment if name includes a ".eps" extension. If name has neither extension, both segments are searched, first after adding the appropriate extension to name, then for name alone, without an extension. If it finds sections in both segments, it creates both EPS and TIFF representations of the image. | |
| 2. | Next, it searches for name files in the lproj directories in the application's main bundle. It searches for all file types (extensions) handled by all registered NXImageReps; by default, the files searched for include those with the extension "tiff", "tif", and "eps". It searches the language directories that the user specified for this application, or (if none) those specified by the user's default language preferences (see Application's systemLanguages method). | |
| 3. | Finally, if there's no file named name in the main bundle's relevant language directories, it looks for name files in the main bundle (but outside the lproj directories). Again, it searches for all file types handled by all registered NXImageReps. |
| If a section or file contains data for more than one image, a separate representation is created for each one. 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 on the section name or file name. This method treats all images found in the _ _ICON segment as application or document icons, since the point of putting an image in that segment rather than in _ _TIFF or _ _EPS is to advertise it to the Workspace Manager. The Workspace Manager requires icons to be no more than 48 pixels wide by 48 pixels high. Therefore, an NXImage created from an _ _ICON section has its size set to 48.0 by 48.0 and is made scalable. The image returned by this method should not be freed, unless it's certain that no other objects reference it. See also: |
| imageFileTypes |
| + (const char *const *)imageFileTypes |
| Returns a null-terminated array of strings representing file types for which a registered NXImageRep exists. This list includes all file types supported by registered subclasses of NXImageRep, and those types that can be converted to supported file types through a user-installed filter service. The array returned by this method may be passed directly to the OpenPanel's runModalForTypes: method. The returned array belongs to the system, and should not be freed by the application.
File types are identified by extension. By default, the list returned by this method contains "tiff", "tif", "eps", and, for applications that use the 3D Kit, "rib". When creating a subclass of NXImageRep that accepts image data from non-default file types, override the imageUnfilteredFileTypes method to notify NXImage of the file types your class supports. See also: + imageRepForFiletype:, + imageUnfilteredFileTypes (NXImageRep class) |
| imagePasteboardTypes |
| + (const NXAtom *)imagePasteboardTypes |
| Returns a null-terminated list of pasteboard types for which a registered NXImageRep exists. This list includes all pasteboard types supported by registered subclasses of NXImageRep, and those that can be converted to supported pasteboard types through a user-installed filter service. The returned list belongs to the system, and should not be freed by the application.
By default, the list returned by this method contains "NXPostScriptPboardType," "NXTIFFPboardType," and, for applications that use the 3D Kit, "N3DRIBPboardType." When creating a subclass of NXImageRep that accepts image data from non-default pasteboard types, override the imageUnfilteredPasteboardTypes method to notify NXImage of the pasteboard types your class supports. See also: + imageRepForPasteboardtype:, + imageUnfilteredPasteboardTypes (NXImageRep) |
| imageRepForFileType: |
| + (Class)imageRepForFileType:(const char *)type |
| Returns the NXImageRep subclass that supports files of type. type represents the file extension, which represents the type of data in the file. By default, this method returns the NXBitmapImageRep class for a type of "tiff" or "tif" and the NXEPSImageRep class for a type of "eps". If you create a subclass of NXImageRep that supports other file types, you must override the NXImageRep imageUnfilteredFileTypes class method to return the extensions representing those file types, then register your subclass using NXImage's registerImageRep: class method.
See also: + registerImageRep:, |
| imageRepForPasteboardType: |
| + (Class)imageRepForPasteboardType:(NXAtom)type |
| Returns the NXImageRep subclass that supports pasteboards of type. By default, this method returns NXBitmapImageRep for a type of NXTIFFPboardType and NXEPSImageRep for a type of NXPostscriptPboardType. If type is NXFilenamePboardType, this method returns the registered NXImageRep that supports files with the extension of the file name on the pasteboard, either directly or through a user-installed filter service. If no registered NXImageRep handles data of type, returns nil.
If you create a subclass of NXImageRep that supports other pasteboard types, you must override the NXImageRep class method imageUnfilteredPasteboardTypes to return the extensions representing those pasteboard types, then register your subclass using NXImage's class method registerImageRep:. See also: + registerImageRep:, |
| imageRepForStream: |
| + (Class)imageRepForStream:(NXStream *)stream |
| Returns the NXImageRep subclass that can be instantiated from the data in stream. By default, this method returns NXBitmapImageRep for a stream containing TIFF data, NXEPSImageRep for a stream containing EPS data, and nil for a stream containing an unsupported data type. stream must be seekable.
If you create a subclass of NXImageRep that supports other data types, you must override the NXImageRep canLoadFromStream: class method to determine whether your subclass can be instantiated from data in stream. You must also register your subclass using NXImage's registerImageRep: class method. See also: + registerImageRep:, |
| imageUnfilteredFileTypes |
| + (const char *const *)imageUnfilteredFileTypes |
| This method returns a NULL-terminated list of file types which all the image reps registered with NXImage can load from. This list belongs to the NXImage and should not be freed or changed: |
| imageUnfilteredPasteboardTypes |
| + (const NXAtom *)imageUnfilteredPasteboardTypes |
| This method returns a NULL-terminated list of pasteboard types which all the image reps registered with NXImage can load from. This list belongs to the NXImage and should not be freed or changed: |
| registerImageRep: |
| + (void)registerImageRep:imageRepClass |
| Informs NXImage of the existence of a subclass of NXImageRep.
This method adds the class to NXImage's list of image reps without verifying the behavior of imageRepClass. When the application calls NXImage class methods such as imageFileTypes, imagePasteboardTypes, and imageRepForFileType, the class checks this list to find the types of image data it can support. imageRepClass must implement the methods imageUnfilteredFileTypes, imageUnfilteredPasteboardTypes, and canLoadFromStream: to inform NXImage of the data types it supports. This method may be invoked multiple times; imageRepClass is added to NXImage's list of image reps only the first time it is invoked. See also: + imageFileTypes, + imagePasteboardTypes, + imageRepForFileType, NXImageRep class description |
| unregisterImageRep: |
| + (void)unregisterImageRep:imageRepClass |
| Informs NXImage of the resignation of a subclass of NXImageRep.
See also: + registerImageRep: |
| Instance Methods |
| backgroundColor |
| (NXColor)backgroundColor |
| Returns the background color of the rectangle where the image is cached. If no background color has been specified, NX_COLORCLEAR is returned, indicating a totally transparent background.
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. See also: |
| bestRepresentation |
| (NXImageRep *)bestRepresentation |
| Returns the image representation that best matches the display device with the deepest frame buffer currently available to the Window Server.
See also: |
| composite:fromRect:toPoint: |
| composite:(int)op |
| fromRect:(const NXRect *)aRect toPoint:(const NXPoint *)aPoint |
| Composites the area enclosed by the aRect rectangle to the location specified by aPoint in the current coordinate system. The op and aPoint arguments are the same as for composite:toPoint:. 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 NXImage cache its representations in their own individual windows (with the setUnique: 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. If successful in compositing (or printing) the image, this method returns self. If not, it returns nil. See also: |
| composite:toPoint: |
| composite:(int)op toPoint:(const NXPoint *)aPoint |
| Composites the image to the location specified by aPoint. The first argument, op, names the type of compositing operation requested. It should be one of the following constants: |
| NX_CLEAR | NX_SOVER | NX_DOVER | NX_XOR | |
| NX_COPY | NX_SIN | NX_DIN | ||
| NX_PLUSD | NX_SOUT | NX_DOUT | ||
| NX_PLUSL | NX_SATOP | NX_DATOP |
| aPoint is specified in the current coordinate system--the coordinate system of the currently focused View--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.
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. If successful in compositing (or printing) the image, this method returns self. If not, it returns nil. See also: |
| copyFromZone: |
| copyFromZone:(NXZone *)zone |
| Returns a new instance of NXImage that's an exact copy of the receiver. Memory for the new instance is allocated from zone. Cached image reps are copied fully, the new NXImage has its own copy of the image data. Lazily allocated image reps are copied with only source information (for example, file names); the image can be recreated from this source when the NXImage is asked to composite itself.
See also: |
| delegate |
| delegate |
| Returns the delegate of the NXImage object, or nil if no delegate has been set.
See also: |
| dissolve:fromRect:toPoint: |
| dissolve:(float)delta |
| fromRect:(const NXRect *)aRect toPoint:(const NXPoint *)aPoint |
| Composites the aRect portion of the image to the location specified by aPoint, just as composite:fromRect:toPoint: does, but uses the dissolve operator rather than composite. delta is a fraction between 0.0 and 1.0 that specifies how much of the resulting composite will come from the NXImage. If the source image contains alpha, this operation may promote the destination Window.
When printing, this method is identical to composite:fromRect:toPoint:. The delta argument is ignored. If successful in compositing (or printing) the image, this method returns self. If not, it returns nil. See also: |
| dissolve:toPoint: |
| dissolve:(float)delta toPoint:(const NXPoint *)aPoint |
| Composites the image to the location specified by aPoint, just as composite:toPoint: does, but uses the dissolve operator rather than composite. delta is a fraction between 0.0 and 1.0 that specifies how much of the resulting composite will come from the NXImage. If the source image contains alpha, this operation may promote the destination Window.
To slowly dissolve one image into another, this method (or dissolve:fromRect:toPoint:) needs to be invoked repeatedly with an ever-increasing delta. Since delta 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 composite:toPoint:. The delta argument is ignored. If successful in compositing (or printing) the image, this method returns self. If not, it returns nil. See also: |
| drawRepresentation:inRect: |
| (BOOL)drawRepresentation:(NXImageRep *)imageRep |
| inRect:(const NXRect *)rect |
| Fills the specified rectangle with the background color, then sends the imageRep a drawIn: message to draw itself inside the rectangle (if the NXImage is scalable), or a drawAt: message to draw itself at the location of the rectangle (if the NXImage is not scalable). The rectangle is located in the current window and is specified in the current coordinate system.
This method shouldn't be called directly; the NXImage 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. This method returns the value returned by the drawIn: or drawAt: method, which indicates whether or not the representation was successfully drawn. When NO is returned, the NXImage will ask another representation, if there is one, to draw the image. If the background color is fully transparent and the image is not being cached by the NXImage, the rectangle won't be filled before the representation draws. See also: |
| finishUnarchiving |
| finishUnarchiving |
| Registers the name of the newly unarchived receiver, if it has a name, and returns nil. It also returns nil if the receiving NXImage doesn't have a name. However, if the receiver has a name that can't be registered because it's already in use, this method frees the receiver and returns the existing NXImage with that name, thus replacing the unarchived object with one that's already in use.
finishUnarchiving messages are generated automatically (by NXReadObject()) after the object has be unarchived (by read:) and initialized (by awake). |
| free |
| free |
| Deallocates the NXImage and all its representations. If the object had been assigned a name, the name is removed from the class database.
Images that are obtained through findImageNamed: should not be freed unless it's certain that no other part of the program has similarly obtained a reference to the same object. See also: + findImageNamed: |
| getImage:rect: |
| getImage:(NXImage **)theImage rect:(NXRect *)theRect |
| Provides information about the receiving NXImage object, if it's a subimage of another NXImage. The parent NXImage is assigned to the variable referred to by theImage, and the rectangle where the receiver is located in that NXImage is copied into the structure referred to by theRect.
If the receiver is not a subimage of another NXImage object (if it wasn't initialized by initFromImage:rect:), the variable referred to by theImage is set to nil and the rectangle is not modified. Returns self. See also: |
| getSize: |
| getSize:(NXSize *)theSize |
| Copies the size of the image into the structure specified by theSize. If no size has been set, all values in the structure will be set to 0.0. Returns self.
See also: |
| init |
| init |
| Initializes the receiver, a newly allocated NXImage instance, but does not set the size of the image. The size must be set, and at least one image representation provided, before the NXImage object can be used. The size can be set either through a setSize: message or by providing a representation that specifies a size.
See also: |
| initFromFile: |
| initFromFile:(const char *)filename |
| Initializes the receiver, a newly allocated NXImage instance, for the file filename. This method initializes lazily: the NXImage doesn't actually open filename or create an image representation from its data until an application attempts to composite or requests information about the NXImage. (Use the method loadFromFile: to immediately create an image representation for the data in a file.)
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 NXImageRep subclass that handles that data type from among those registered with NXImage. By default, the files handled are those with the extensions "tiff", "tif", 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 an image representation for the data, your application should do error checking before attempting to use the image; one way to do so is by invoking the lockFocus method to check whether the image can be drawn. This method uses the useFromFile: method to register filename. It's equivalent to a combination of init and useFromFile:. See also: |
| initFromImage:rect: |
| initFromImage:(NXImage *)image rect:(const NXRect *)rect |
| Initializes the receiver, a newly allocated NXImage instance, so that it's a subimage for the rect portion of another NXImage object, image. The size of the new object is set from the size of the rect rectangle. Returns self.
Once initialized, the new instance can't be altered and will remain dependent on the original image. Changes made to the original will also change the subimage. Subimages should be used only as a way of avoiding composite:fromRect:toPoint: and dissolve:fromRect:toPoint: messages. They permit you to divide a large image into sections and assign each section a name. The name can then be passed to those Button and Cell methods that identify images by name rather than id. See also: |
| initFromPasteboard: |
| initFromPasteboard:(Pasteboard *)pasteboard |
| Initializes and returns the receiver, a newly allocated NXImage instance, from pasteboard. pasteboard should be of a type returned by one of the registered NXImageRep's imageUnfilteredPasteboardTypes methods; the default types supported are NXPostscriptPboardType (NXEPSImageRep) and NXTIFFPboardType (NXBitmapImageRep). If pasteboard is an NXFilenamePboardType, the file name should have an extension returned by one of the registered NXImageRep's imageUnfilteredFileTypes methods; the default types supported are "tiff", "tif", (NXBitmapImageRep) and "eps" (NXEPSImageRep).
If the data type on the pasteboard isn't supported by a registered NXImageRep, this method frees the receiver and returns nil. Otherwise this method invokes initFromStream to initialize the image. See also: + registerImageRep: |
| initFromSection: |
| initFromSection:(const char *)name |
| Initializes the receiver, a newly allocated NXImage instance, on a resource name in the application directory. This method initializes lazily: the NXImage doesn't actually create a representation for the data in name until an application attempts to composite or requests information about the NXImage. When it does create a representation for name, the NXImage will look for data in the application's bundle.
For historical reasons, the mechanism that actually creates the image representation first looks for name in the application's executable file. It looks for a section with TIFF data in the _ _TIFF segment if name includes a ".tiff" extension, or for a section containing EPS data in the _ _EPS segment if name includes a ".eps" extension. If name has neither extension, both segments are searched, first after adding the appropriate extension to name, then for name alone, without an extension. If it finds sections in both segments, it creates both EPS and TIFF representations of the image. Next, the mechanism searches for name files in the lproj directories in the application's main bundle. It searches for all file types (extensions) handled by all registered NXImageReps; by default, the files searched for include those with the extension "tiff", "tif", and "eps". It searches the language directories that the user specified for this application, or (if none) those specified by the user's default language preferences (see the Application class systemLanguages method). If a file name is found with no extension, the mechanism opens the file and looks for a registered subclass of NXImageRep that can handle the data (using the NXImage imageRepForStream: class method). If a section contains EPS or TIFF data for more than one version of the image, a representation will be created and added to the NXImage for each image specified. If an application bundle contains more than one file named name (each with a different extension), a representation will be created and added to the NXImage for each file whose data type is supported by a registered subclass of NXImageRep. The size of the NXImage is set from image representation data. After finishing the initialization, this method returns self. However, if the new instance can't be initialized, it's freed and nil is returned. This method uses the useFromSection: method to register name. It's equivalent to a combination of init and useFromSection:. See also: |
| initFromStream: |
| initFromStream:(NXStream *)stream |
| Initializes the receiver, a newly allocated NXImage instance, with the image or images specified in the data read from stream, and returns self. If the receiver can't be initialized for any reason, it's freed and nil is returned.
Since this method must store the data read from the stream or render the specified image immediately, it's less preferred than initFromSection: or initFromFile:, which can wait until the image is needed. The stream must be seekable and should contain image data recognizable to a registered NXImageRep subclass. It's read using the loadFromStream: method, which will set the size of the NXImage from information found in the representation data. This method is equivalent to a combination of init and loadFromStream:. See also: |
| initSize: |
| initSize:(const NXSize *)aSize |
| Initializes the receiver, a newly allocated NXImage instance, to the size specified and returns self. The size should be specified in units of the base coordinate system. It must be set before the NXImage can be used.
This method is the designated initializer for the class (the method that incorporates the initialization of classes higher in the hierarchy through a message to super). All other init... methods defined in this class work through this method. See also: |
| isCacheDepthBounded |
| (BOOL)isCacheDepthBounded |
| Returns YES if the depth of off-screen windows where the NXImage's representations are cached is bounded by the application's default depth limit, and NO if the depth of the caches can exceed that limit. The default is YES.
See also: |
| isColorMatchPreferred |
| (BOOL)isColorMatchPreferred |
| Returns YES if, when selecting the representation it will use, the NXImage first looks for one that matches the color capability of the rendering device (choosing a gray-scale representation for a monochrome device and a color representation for a color device), then if necessary narrows the selection by looking for one that matches the resolution of the device. If the return is NO, the NXImage first looks for a representation that matches the resolution of the device, then tries to match the representation to the color capability of the device. The default is YES.
See also: |
| isDataRetained |
| (BOOL)isDataRetained |
| Returns YES if the NXImage retains the data needed to render the image, and NO if it doesn't. The default is NO. If the data is available in a section of the application executable or in a file that won't be moved or deleted, or if responsibility for drawing the image is delegated to another object with a custom method, there's no reason for the NXImage to retain the data. However, if the NXImage reads image data from a stream, you may want to have it keep the data itself; for example, to render the same image on another device at a different resolution.
See also: |
| isEPSUsedOnResolutionMismatch |
| (BOOL)isEPSUsedOnResolutionMismatch |
| Returns YES if an EPS representation of the image should be used whenever it's impossible to match the resolution of the device to the resolution of another representation of the image (a TIFF representation, for example). By default, this method returns NO to indicate that EPS representations are not necessarily preferred.
See also: |
| isFlipped |
| (BOOL)isFlipped |
| Returns YES if a flipped coordinate system is used when locating the image, and NO if it isn't. The default is NO.
See also: |
| isMatchedOnMultipleResolution |
| (BOOL)isMatchedOnMultipleResolution |
| Returns YES if the resolution of the device and the resolution specified for the image are considered to match if one is a multiple of the other, and NO if device and image resolutions are considered to match only if they are exactly the same. The default is YES.
See also: |
| isScalable |
| (BOOL)isScalable |
| Returns YES if image representations are scaled to fit the size specified for the NXImage. If representations are not scalable, this method returns NO. The default is NO.
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 NXImage. See also: |
| isUnique |
| (BOOL)isUnique |
| Returns YES if each representation of the image is cached alone in an off-screen window of its own, and NO if they can be cached in off-screen windows together with other images. A return of NO doesn't mean that the windows are, in fact, shared, just that they can be. The default is NO.
See also: |
| lastRepresentation |
| (NXImageRep *)lastRepresentation |
| Returns the last representation that was specified for the image (the last one added with methods like useCacheWithDepth:, loadFromStream:, and initFromStream:). If the NXImage has no representations, this method returns nil.
See also: |
| loadFromFile: |
| (BOOL)loadFromFile:(const char *)filename |
| Creates an image representation from the data read from filename and adds it to the receiving NXImage's list of representations. This method is equivalent to mapping the file to memory, then invoking loadFromStream:.
filename may be a full or relative pathname, and should include an extension that identifies the data type in the file. This method looks for an NXImageRep subclass that handles that data type from among those registered with NXImage. By default, the files handled are those with the extensions "tiff", "tif", and "eps". If the file name has no extension, or the extension is one not recognized by one of the registered subclasses of NXImageRep, this method opens a stream on the file and attempts to find a registered subclass of NXImageRep that can handle the data in the stream. If a file containing TIFF or EPS data includes more than one image, a separate representation is created for each one. If the NXImage object doesn't retain image data (isDataRetained returns NO), the image will be rendered in an off-screen window and the representations will be of type NXCachedImageRep. If the data is retained, the representations will be of type NXBitmapImageRep or NXEPSImageRep, depending on the data. If successful in creating at least one representation, this method returns YES. If not, it returns NO. See also: |
| loadFromStream: |
| (BOOL)loadFromStream:(NXStream *)stream |
| Creates an image representation from the data read from stream and adds it to the receiving NXImage's list of representations. The stream must be seekable, and the data must be of a type recognized by a registered NXImageRep. If the size of the NXImage hasn't yet been set, it will be set from information found in the TIFF fields or from the EPS bounding box comment. If the stream contains data specifying more than one image, a separate representation is created for each one.
If the NXImage object doesn't retain image data (isDataRetained returns NO), the image will be rendered in an off-screen window and the representations will be of type NXCachedImageRep. If the data is retained, the representations will be of type NXBitmapImageRep or NXEPSImageRep, depending on the data. If successful in creating at least one representation, this method returns YES. If not, it returns NO. See also: |
| lockFocus |
| (BOOL)lockFocus |
| Focuses on the best representation for the NXImage, by making the off-screen window where the representation will be cached the current window and a coordinate system specific to the area where the image will be drawn the current coordinate system. The best representation is the one that best matches the deepest available frame buffer; it's the same object returned by the bestRepresentation method.
If the NXImage has no representations, lockFocus creates one with the useCacheWithDepth: method, specifying the best depth for the deepest frame buffer currently in use. To add additional representations, useCacheWithDepth: messages must be sent explicitly. This method returns YES if it's successful in focusing on the representation, and NO if not. A successful lockFocus message must be balanced by a subsequent unlockFocus message to the same NXImage. These messages bracket the code that draws the image. lockFocus returns NO when the image can't be drawn; for example, because the file from which it was initialized is non-existent, or the data in that file is invalid. In this case, lockFocus will not have altered the current graphics state and should not be balanced by an unlockFocus message (in this regard, the NXImage lockFocus method differs from that of View). See also: |
| lockFocusOn: |
| (BOOL)lockFocusOn:(NXImageRep *)imageRep |
| Focuses on the imageRep representation, by making the off-screen window where it will be cached the current window and a coordinate system specific to the area where the image will be drawn the current coordinate system.
This method returns YES if it's successful in focusing on the representation, and NO if it's not. A successful lockFocusOn: message must be balanced by a subsequent unlockFocus message to the same receiver. These messages bracket the code that draws the image. The useCacheWithDepth: method will add a representation specifically for this purpose. For example: |
[myNXImage useCacheWithDepth:NX_TwoBitGrayDepth];
if ( [myNXImage lockFocusOn:[myImage lastRepresentation]] ) {
/* drawing code goes here */
[myNXImage unlockFocus];
}
| If lockFocusOn: returns NO, it will not have altered the current graphics state and should not be balanced by an unlockFocus message.
See also: |
| name |
| (const char *)name |
| Returns the name assigned to the NXImage, or NULL if no name has been assigned.
See also: |
| read: |
| read:(NXTypedStream *)stream |
| Reads the NXImage and all its representations from the typed stream stream.
See also: |
| recache |
| recache |
| Invalidates the off-screen caches of all representations and frees them. The next time any representation is composited, it will first be asked to redraw itself in the cache. NXCachedImageReps aren't destroyed by this method.
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. Returns self. |
| removeRepresentation: |
| removeRepresentation:(NXImageRep *)imageRep |
| Frees the imageRep representation after removing it from the NXImage's list of representations. Returns self.
See also: |
| representationList |
| (List *)representationList |
| Returns the List object containing all the representations of the image. The List belongs to the NXImage object, and there's no guarantee that the same List object will be returned each time. Therefore, rather than saving the object that's returned, you should ask for it each time you need it.
See also: |
| setBackgroundColor: |
| setBackgroundColor:(NXColor)aColor |
| Sets the background color of the image. The default is NX_COLORCLEAR, indicating a totally transparent background. The background color will be visible only for representations that don't completely cover all the pixels within the image when drawing. The background color is ignored for cached image representations (such as those created with useCacheWithDepth:); such caches are always created with a white background. This method doesn't cause the receiving NXImage to recache itself. Returns self.
See also: |
| setCacheDepthBounded: |
| setCacheDepthBounded:(BOOL)flag |
| Determines whether the depth of the off-screen windows where the NXImage's representations are cached should be limited by the application's default depth limit. If flag is NO, window depths will be determined by the specifications of the representations, rather than by the current display devices. The default is YES. This method doesn't cause the receiving NXImage to recache itself. Returns self.
See also: |
| setColorMatchPreferred: |
| setColorMatchPreferred:(BOOL)flag |
| Determines how the NXImage will select which representation to use. If flag is YES, it first tries to match the representation to the color capability of the rendering device (choosing a color representation for a color device and a gray-scale representation for a monochrome device), and then if necessary narrows the selection by trying to match the resolution of the representation to the resolution of the device. If flag is NO, the NXImage first tries to match the representation to the resolution of the device, and then tries to match it to the color capability of the device. The default is YES. Returns self.
See also: |
| setDataRetained: |
| setDataRetained:(BOOL)flag |
| Determines whether the NXImage retains the data needed to render the image. The default is NO. If the data is available in a section of the application executable or in a file that won't be moved or deleted, or if responsibility for drawing the image is delegated to another object with a custom method, there's no reason for the NXImage to retain the data. However, if the NXImage reads image data from a stream, you may want to have it keep the data itself. Generally, this is useful to redraw the image to a device of different resolution.
If an image representation is created lazily (through the useFromFile: or useFromSection: methods), the only data retained is the source name. See also: |
| setDelegate: |
| setDelegate:anObject |
| Makes anObject the delegate of the NXImage. Returns self.
See also: |
| setEPSUsedOnResolutionMismatch: |
| setEPSUsedOnResolutionMismatch:(BOOL)flag |
| Determines whether EPS representations will be preferred when there are no representations that match the resolution of the device. The default is NO. Returns self.
See also: |
| setFlipped: |
| setFlipped:(BOOL)flag |
| Determines whether the polarity of the y-axis is inverted when drawing an image. If flag is YES, the image will have its coordinate origin in the upper left corner and the positive y-axis will extend downward. This method affects only the coordinate system used to draw the image, whether through a method assigned with the useDrawMethod:object: method or directly by focusing on a representation. It doesn't affect the coordinate system for specifying portions of the image for methods like composite:fromRect:toPoint: or initFromImage:rect:. This method doesn't cause the receiving NXImage to recache itself. Returns self.
See also: |
| setMatchedOnMultipleResolution: |
| setMatchedOnMultipleResolution:(BOOL)flag |
| Determines whether image representations with resolutions that are exact multiples of the resolution of the device are considered to match the device. The default is YES. Returns self.
See also: |
| setName: |
| (BOOL)setName:(const char *)string |
| Sets string to be the name of the NXImage object and registers it under that name. If the object already has a name, that name is discarded. If string is already the name of another object or if the receiving NXImage is one of the system bitmaps provided by the Application Kit, the assignment fails.
If successful in naming or renaming the receiver, this method returns YES. Otherwise it returns NO. See also: + findImageNamed:, |
| setScalable: |
| setScalable:(BOOL)flag |
| Determines whether representations with sizes that differ from the size of the NXImage will be scaled to fit. The default is NO.
Generally, representations that are created through NXImage methods (such as useCacheWithDepth: or initFromSection:) have the same size as the NXImage. However, a representation that's added with the useRepresentation: method 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 NXImage to recache itself when it is next composited. Returns self. See also: |
| setSize: |
| setSize:(const NXSize *)aSize |
| Sets the width and height of the image. The size referred to by aSize should be in units of the base coordinate system. The size of an NXImage must be set before it can be used. Returns self.
The size of an NXImage can be changed 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. See also: |
| setUnique: |
| setUnique:(BOOL)flag |
| Determines whether each image representation will be cached in its own off-screen window or in a window shared with other images. If flag is YES, each representation is guaranteed to be in a separate window. If flag is NO, a representation can be cached together with other images, though in practice it might not be. The default is NO.
If an NXImage is to be resized frequently, it's more efficient to cache its representations in unique windows. This method does not invalidate any existing caches. Returns self. See also: |
| unlockFocus |
| unlockFocus |
| Balances a previous lockFocus or lockFocusOn: message. All successful lockFocus and lockFocusOn: messages (those that return YES) must be followed by a subsequent unlockFocus message. Those that return NO should never be followed by unlockFocus.
Returns self. See also: |
| useCacheWithDepth: |
| (BOOL)useCacheWithDepth:(NXWindowDepth)depth |
| Creates a representation of type NXCachedImageRep and adds it to the NXImage's list of representations. Initially, the representation is nothing more than an empty area equal to the size of the image in an off-screen window with the specified depth. You must focus on the representation and draw the image. The following code shows how an NXImage might be created with the same appearance as a View. |
id myImage;
NXRect theRect;
[myView getBounds:&theRect];
myImage = [[NXImage alloc] initSize:&frameRect.size];
[myImage useCacheWithDepth:NX_DefaultDepth];
if ( [myImage lockFocus] ) {
[myView drawSelf:&theRect :1];
[myImage unlockFocus];
}
| depth should be one of the following enumerated values: |
| NX_DefaultDepth NX_TwoBitGrayDepth NX_EightBitGrayDepth NX_TwelveBitRGBDepth NX_TwentyFourBitRGBDepth |
| If successful in adding the representation, this method returns YES. If the size of the image has not been set or the cache can't be created for any other reason, it returns NO. |
| useDrawMethod:inObject: |
| (BOOL)useDrawMethod:(SEL)aSelector inObject:anObject |
| Creates a representation of type NXCustomImageRep and adds it to the NXImage object's list of representations. aSelector should name a method that can draw the image in the NXImage object's coordinate system, and that takes a single argument, an NXCustomImageRep. anObject should be the object that can perform the method.
This type of representation allows you to delegate responsibility for creating an image to another object within the program. After invoking this method, you may need to explicitly set features of the newly created NXCustomImageRep, such as size, number of colors, and so on. This is true in particular if the NXImage has multiple image representations to choose from. A list of methods used to complete initialization is found in the class specification for NXCustomImageRep. Use NXImage's lastRepresentation method to access the newly created representation. This method returns YES if it's successful in creating the representation, and NO if it's not. |
| useFromFile: |
| (BOOL)useFromFile:(const char *)filename |
| Adds filename to the list of data sources used by the receiving NXImage. This method initializes lazily: the NXImage doesn't actually open filename or create an image representation from its data until an application attempts to composite or requests information about the NXImage. (Use the method loadFromFile: to immediately create an image representation for the data in a file.)
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 NXImageRep subclass that handles that data type from among those registered with NXImage. By default, the files handled are those with the extensions "tiff", "tif", and "eps". If a representation can be added to the NXImage, this method returns YES. If not, it returns NO. In the current implementation, it may return YES even if the filename file doesn't exist or contains bad data. To catch such cases, your application should check the value returned by the lockFocus methods or implement the delegate method imageDidNotDraw:inRect:. If filename contains TIFF or EPS data specifying more than one image, a separate representation is added for each one. See also: |
| useFromSection: |
| (BOOL)useFromSection:(const char *)name |
| Adds name to the list of data sources used by the receiving NXImage. This method initializes lazily: the NXImage doesn't actually create a representation for the data in name until an application attempts to composite or requests information about the NXImage. When it does create a representation for name, the NXImage will look for data in the application's bundle.
For historical reasons, the mechanism that actually creates the image representation first looks for name in the application's executable file. It looks for a section with TIFF data in the _ _TIFF segment if name includes a ".tiff" extension, or for a section containing EPS data in the _ _EPS segment if name includes a ".eps" extension. If name has neither extension, both segments are searched, first after adding the appropriate extension to name, then for name alone, without an extension. If it finds sections in both segments, it creates both EPS and TIFF representations of the image. Next, the mechanism searches for name files in the lproj directories in the application's main bundle. It searches for all file types (extensions) handled by all registered NXImageReps; by default, the files searched for include those with the extension "tiff", "tif", and "eps". It searches the language directories that the user specified for this application, or (if none) those specified by the user's default language preferences (see Application's systemLanguages method). If a file name is found with no extension, the mechanism opens the file and looks for a registered NXImageRep subclass that can handle the data (using the NXImage's imageRepForStream: class method). If a section contains EPS or TIFF data for more than one version of the image, a representation will be created and added to the NXImage for each image specified. If an application bundle contains more than one file named name (each with a different extension), a representation will be created and added to the NXImage for each file whose data type is supported by a registered subclass of NXImageRep. The size of the NXImage is set from information taken from the TIFF fields or the EPS bounding box comment. This method returns YES if a representation can be added to the NXImage, and NO if not. In the current implementation, it may return YES even if the section matching name contains bad data or no such section can be found. See also: |
| useRepresentation: |
| (BOOL)useRepresentation:(NXImageRep *)imageRep |
| Adds imageRep to the receiving NXImage object's list of representations. If successful in adding the representation, this method returns YES. If not, it returns NO.
Any representation that's added by this method will belong to the NXImage and will be freed when the NXImage is freed. Representations can't be shared among NXImages. After invoking this method, you may need to explicitly set features of the new representation, such as size, number of colors, and so on. This is true in particular if the NXImage has multiple image representations to choose from. A list of methods used to complete initialization is found in the class description for NXCustomImageRep. See also: |
| write: |
| write:(NXTypedStream *)stream |
| Writes the NXImage and all its representations to the typed stream stream. Representations created with useFromFile: or useFromStream: methods archive only the name of the data source. Representations created with the loadFromFile: or loadFromStream: methods or added via useRepresentation: method will archive the data for the image.
See also: |
| writeTIFF: |
| writeTIFF:(NXStream *)stream |
| Writes TIFF data for the representation that best matches the display device with the deepest frame buffer to stream. This method is a shorthand for writeTIFF:allRepresentations: with a flag of NO. Returns self. |
| writeTIFF:allRepresentations: |
| writeTIFF:(NXStream *)stream allRepresentations:(BOOL)flag |
| Writes TIFF data for the representations to stream. If flag is YES, data will be written for each of the representations. If flag is NO, data will be written only for the representation that best matches the display device with the deepest frame buffer. Returns self.
If stream is positioned anywhere but at the beginning of the stream, this method will append the representation(s) it writes to the TIFF data it assumes is already in the stream. To do this, it must be able to read the TIFF header from the stream. Therefore, the stream must be opened for NX_READWRITE permission and must be seekable. |
| writeTIFF:allRepresentations:usingCompression:andFactor: |
| writeTIFF:(NXStream *)stream |
| allRepresentations:(BOOL)flag usingCompression:(int)compressionType andFactor:(float)compressionFactor |
| Writes TIFF data for the representations to stream. If flag is YES, data will be written for each of the representations. If flag is NO, data will be written only for the representation that best matches the display device with the deepest frame buffer. The compression arguments let you specify a type of compression and the compression amount. The compression types are listed in the section "Types and Constants." compressionFactor provides a hint for those compression types that implement variable comression ratios; currently only JPEG compression uses compressionFactor. Returns self. |
| Method Implemented By The Delegate |
| imageDidNotDraw:inRect: |
| (NXImage *)imageDidNotDraw:sender inRect:(const NXRect *)aRect |
| Implemented by the delegate to respond to a message sent by the sender NXImage when the sender was unable, for whatever reason, to composite or lock focus on its image. The delegate can return another NXImage to draw in the sender's place. If not, it should return nil to indicate that sender should give up the attempt at drawing the image. |