ADC Home > Reference Library > Reference > Legacy Documents > Cocoa > Application Kit Reference for Java (Legacy) >

Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

NSImage

Inherits from
Implements
Package
com.apple.cocoa.application
Companion guide
Drawing and Images

Overview

An NSImage object contains an image that can be composited anywhere without first being drawn in any particular view.

Tasks

Constructors

Setting the Size of the Image

Referring to Images by Name

Specifying the Image

Using the Image

Choosing Which Image Representation to Use

Getting the Representations

Determining How the Image Is Stored

Drawing the Image

Determining How the Image Is Drawn

Assigning a Delegate

Producing TIFF Data for the Image

Testing Image Data Sources

Incremental Loading

Loading an image

Drawing an image

Constructors

NSImage

Creates an empty NSImage with a zero-sized frame rectangle.

public NSImage()

Creates an NSImage based on byReferencing.

public NSImage(String filename, boolean byReferencing)

Discussion

If byReferencing is true, the NSImage doesn’t actually open filename or create image representations from its data until an application attempts to composite or requests information about the NSImage.

The setDataRetained is invoked with an argument of true, thus enabling the image to hold onto its filename. Note that if an image created by referencing is archived, only the filename will be saved.

If byReferencing is false, filename is opened, and one or more image representations is created from its data.

In both cases, filename may be a full or relative pathname and should include an extension that identifies the data type in the file. If byReferencing is true, the constructor will look for an NSImageRep subclass that handles that data type from among those registered with NSImage. If byReferencing is false, the mechanism that actually creates the image representation for filename will look for an NSImageRep subclass that handles that data type from among those registered with NSImage.

If byReferencing is false and at least one image representation can’t be created from the contents of filename, null is returned.If byReferencing is true and the new instance can’t be initialized, null is returned. Since creating by reference doesn’t actually create image representations for the data, your application should do error checking before attempting to use the image; one way to do so is by invoking the isValid method to check whether the image can be drawn.

Creates a new NSImage, setting its size to aSize.

public NSImage(NSSize aSize)

Discussion

The size should be specified in units of the base coordinate system. Although you can create an NSImage without specifying a size by passing a size of (0.0, 0.0), the NSImage’s size must be set before it can be used.

Creates a new NSImage, with the contents of the data object aData.

public NSImage(NSData aData)

Discussion

If unable to create one or more image representations from aData, null is returned.

Creates a new NSImage, with the contents of the URL aURL.

public NSImage(java.net.URL aURL)

Discussion

If at least one image representation can’t be created from the contents of aURL, null is returned.

Creates a new NSImage instance for the file at url.

public com.apple.cocoa.application.NSImage(URL url, boolean)

Discussion

This constructor initializes lazily: The NSImage doesn’t actually open url or create image representations from its data until an application attempts to composite or requests information about the NSImage.

The URL should include an extension that identifies the data type in the file. The mechanism that actually creates the image representation for url will look for an NSImageRep subclass that handles that data type from among those registered with NSImage.

After finishing the initialization, this method returns the NSImage. However, if the new instance can’t be initialized, it’s freed and null is returned. Since this constructor doesn’t actually create image representations for the data, your application should do error checking before attempting to use the image; one way to do so is by invoking the isValid method to check whether the image can be drawn.

This method invokes setDataRetained with an argument of true, thus enabling it to hold onto its URL. Note that if an image created with this method is archived, only the URL will be saved.

Availability

Creates a new NSImage, with data from aPasteboard.

public NSImage(NSPasteboard aPasteboard)

Discussion

The aPasteboard object should contain a type returned by one of the registered NSImageRep’s imageUnfilteredPasteboardTypes methods; the default types supported are NSPasteboard.PostscriptPboardType (NSEPSImageRep), NSPasteboard.PDFPboardType (NSPDFImageRep), NSPasteboard.PICTPboardType (NSPICTImageRep), and NSPasteboard.TIFFPboardType (NSBitmapImageRep). If aPasteboard contains a NSPasteboard.FilenamesPboardType, the filename should have an extension returned by one of the registered NSImageRep’s imageUnfilteredFileTypes methods; the default types supported include “tiff”, “gif”, “jpg” (all in NSBitmapImageRep), “pdf” (NSPDFImageRep), “pict” (NSPICTImageRep), and “eps” (NSEPSImageRep).

If unable to create one or more image representations, null is returned.

Static Methods

canInitWithPasteboard

Tests whether the receiver can create an instance of itself from the data represented by pasteboard.

public static boolean canInitWithPasteboard(NSPasteboard pasteboard)

Discussion

Returns true if the receiver’s list of registered NSImageReps includes a class that can handle the data represented by pasteboard.

NSImage uses the NSImageRep class method imageUnfilteredPasteboardTypes to find a class that can handle the data in pasteboard. When creating a subclass of NSImageRep that accepts image data from a nondefault pasteboard type, override the imageUnfilteredPasteboardTypes method to notify NSImage of the pasteboard types your class supports.

See Also

imageFileTypes

Returns an array of strings representing those file types for which a registered NSImageRep exists.

public static NSArray imageFileTypes()

Discussion

This list includes all file types supported by registered subclasses of NSImageRep, plus 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 NSOpenPanel’s runModalForTypes method.

File types are identified by extension and HFS file types.

When creating a subclass of NSImageRep that accepts image data from nondefault file types, override NSImageRep’s imageUnfilteredFileTypes method to notify NSImage of the file types your class supports.

See Also

imageNamed

Returns the NSImage instance associated with name.

public static NSImage imageNamed(String name)

Discussion

The returned object is one that’s been assigned a name with the setName method.

If there’s no known NSImage with name, this method tries to create one by searching for image data in the application’s main bundle (see NSBundle’s class description for a description of how the bundle’s contents are searched). If a file contains data for more than one image, a separate representation is created for each. If an image representation can’t be found for name, no object is created, and null is returned.

The preferred way to name an image is to ask for a name without the extension, but to include the extension for a filename.

One particularly useful image is referenced by the string @"NSApplicationIcon". If you supply this string to imageNamed, the returned image will be the application’s own icon. Icons for other applications can be obtained through the use of methods declared in the NSWorkspace class.

NSImage keeps a reference to the image in a table until the image name is cleared. Consequently you do not need to retain the returned image object unless its name could be cleared. You clear an image name by sending the associated NSImage object a setName message with an argument of null. This message removes the image from the table and autoreleases the object. However, if the image has been fetched elsewhere using imageNamed, then those instances could still be used.

See Also

imagePasteboardTypes

Returns an array of pasteboard types for which a registered NSImageRep exists.

public static NSArray imagePasteboardTypes()

Discussion

This list includes all pasteboard types supported by registered subclasses of NSImageRep and those that can be converted to supported pasteboard types through a user-installed filter service.

By default, the list returned by this method includes NSPasteboard.PDFPboardType, NSPasteboard.PICTPboardType, NSPasteboard.PostScriptPboardType, and NSPasteboard.TIFFPboardType.

When creating a subclass of NSImageRep that accepts image data from nondefault pasteboard types, override NSImageRep’s imageUnfilteredPasteboardTypes method to notify NSImage of the pasteboard types your class supports.

See Also

imageUnfilteredFileTypes

Returns an array of strings representing those file types for which a registered NSImageRep exists.

public static NSArray imageUnfilteredFileTypes()

Discussion

This list consists of all file types supported by registered subclasses of NSImageRep, but does not include 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 NSOpenPanel’s runModalForTypes method.

See Also

imageUnfilteredPasteboardTypes

Returns an array of pasteboard types for which a registered NSImageRep exists.

public static NSArray imageUnfilteredPasteboardTypes()

Discussion

This list consists of all pasteboard types supported by registered subclasses of NSImageRep, but does not include those that can be converted to supported pasteboard types through a user-installed filter service.

See Also

Instance Methods

addRepresentation

Adds imageRep to the receiver’s list of representations.

public void addRepresentation(NSImageRep imageRep)

Discussion

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 fact is true in particular if the NSImage has multiple image representations to choose from. See NSImageRep and its subclasses for the methods you use to complete initialization.

Any representation added by this method is retained by the NSImage. Note that representations can’t be shared among NSImages.

See Also

addRepresentations

Adds each of the representations in imageReps to the receiver’s list of representations.

public void addRepresentations(NSArray imageReps)

Discussion

After invoking this method, you may need to explicitly set features of the new representations, such as size, number of colors, and so on. This fact is true in particular if the NSImage has multiple image representations to choose from. See NSImageRep and its subclasses for the methods you use to complete initialization.

Representations added by this method are retained by the NSImage. Note that representations can’t be shared among NSImages.

See Also

backgroundColor

Returns the background color of the rectangle where the image is cached.

public NSColor backgroundColor()

Discussion

If no background color has been specified, NSColor’s clearColor is returned, indicating a 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.

bestRepresentationForDevice

Returns the best representation for the device described by deviceDescription.

public NSImageRep bestRepresentationForDevice(NSDictionary deviceDescription)

Discussion

If deviceDescription is null, the current device is assumed. “How an Image Representation Is Chosen” outlines the process NSImage goes through to determine the “best” representation for a given device.

See Also

cacheDepthMatchesImageDepth

Returns false if the application’s default depth limit applies to the offscreen windows where the receiver’s representations are cached.

public boolean cacheDepthMatchesImageDepth()

Discussion

If window depths are instead determined by the specifications of the representations, cacheDepthMatchesImageDepth returns true.

See Also

cacheMode

Returns the receiver’s caching mode.

public int cacheMode()

Discussion

Possible return values are described in “Constants.”

Availability
See Also

cancelIncrementalLoad

Immediately cancels the download operation if the image is being incrementally loaded.

public void cancelIncrementalLoad()

Discussion

This call has no effect if the image is not loading.

Availability

compositeToPoint

Composites the image to the location specified by aPoint using the specified compositing operation, op.

public void compositeToPoint(NSPoint aPoint, int op)

Discussion

The aPoint argument specified in the current coordinate system—the coordinate system of the currently focused NSView—and designates where the lower-left corner of the image will appear. The image will have the orientation of the base coordinate system, regardless of the destination coordinates. op should be one of the compositing operations described in “Constants.”

The image is composited from its offscreen 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. Bitmap representations are not cached unless explicitly rendered, by invoking lockFocus and unlockFocus, before compositing.

When printing, the compositing methods do not composite, but attempt to render the same image on the page that compositing would render on the screen, choosing the best available representation for the printer. The op argument is ignored.

See Also

compositeToPointFromRect

Composites the portion of the image enclosed by the srcRect rectangle to the location specified by aPoint in the current coordinate system.

public void compositeToPointFromRect(NSPoint aPoint, NSRect srcRect, int op)

Discussion

The aPoint argument is the same as for compositeToPoint. op should be one of the compositing operations described in “Constants.”

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, when multiple representations are cached in a single window, it can conceivably composite areas that don’t properly belong to the image, if the srcRect rectangle happens to include them. If this inclusion turns out to be a problem, you can prevent it from happening by having the NSImage cache its representations in their own individual windows (with the setCachedSeparately method). In this case, the window’s clipping path will prevent anything but the image from being composited.

Compositing part of an image is as efficient as compositing the whole image, but printing just part of an image is not. When printing, it’s necessary to draw the whole image and rely on a clipping path to be sure that only the desired portion appears.

See Also

compositeToPointFromRectWithFraction

Partially composites the srcRect portion of the image to the location specified by aPoint, using the specified compositing operation, op.

public void compositeToPointFromRectWithFraction(NSPoint aPoint, NSRect srcRect, int op, float delta)

Discussion

Behaves the same as compositeToPointFromRect, except that the delta argument specifies how much of the resulting composite will come from the NSImage object. By invoking repeatedly with delta increasing from 0.0 to 1.0 (refreshing and flushing the destination view between invocations), you gradually fade the original destination into the fully composited image.

See Also

compositeToPointWithFraction

Partially composites the image to the location specified by aPoint, using the specified compositing operation, op.

public void compositeToPointWithFraction(NSPoint aPoint, int op, float delta)

Discussion

Behaves the same as compositeToPoint, except that the delta argument specifies how much of the resulting composite will come from the NSImage object. By invoking repeatedly with delta increasing from 0.0 to 1.0 (refreshing and flushing the destination view between invocations), you gradually fade the original destination into the fully composited image.

See Also

delegate

Returns the delegate of the receiver, or null if no delegate has been set.

public Object delegate()

See Also

dissolveToPoint

Partially composites the image to the location specified by aPoint, just as compositeToPoint does, but uses the CompositeSourceOver operator implicitly.

public void dissolveToPoint(NSPoint aPoint, float delta)

Discussion

delta is a fraction from 0.0 to 1.0 that specifies how much of the resulting composite will come from the NSImage. If the source image contains alpha, this operation may promote the destination NSWindow to contain alpha.

To slowly dissolve one image into another, this method (or dissolveToPointFromRect) 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 replacement is best done in a buffered window before the results of the composite are flushed to the screen.

When printing, this method is identical to compositeToPoint. The delta argument is ignored.

dissolveToPointFromRect

Partially composites the srcRect portion of the image to the location specified by aPoint, just as compositeToPointFromRect does, but uses the CompositeSourceOver operator implicitly.

public void dissolveToPointFromRect(NSPoint aPoint, NSRect srcRect, float delta)

Discussion

delta is a fraction from 0.0 to 1.0 that specifies how much of the resulting composite will come from the NSImage. If the source image contains alpha, this operation may promote the destination NSWindow.

When printing, this method is identical to compositeToPointFromRect. The delta argument is ignored.

See Also

drawAtPoint

Partially composites the srcRect portion of the image to the location point in the current coordinate system, using the specified operation, op.

public void drawAtPoint(NSPoint point, NSRect srcRect, int op, float delta)

Discussion

delta is a fraction from 0.0 to 1.0 that specifies how much of the resulting composite will come from the NSImage. The composite is positioned and oriented according to the current coordinate system. The image is rotated and scaled as needed.

See Also

drawInRect

Partially composites the srcRect portion of the image inside the dstRect portion of the current coordinate system, using the specified operation, op.

public void drawInRect(NSRect dstRect, NSRect srcRect, int op, float delta)

Discussion

delta is a fraction from 0.0 to 1.0 that specifies how much of the resulting composite will come from the NSImage. The composite is positioned and oriented according to the current coordinate system. The image is rotated and scaled as needed.

See Also

drawRepresentationInRect

Fills the specified rectangle with the background color, then sends the imageRep a drawInRect message to draw itself inside the dstRect rectangle (if the NSImage is scalable) or a drawAtPoint message to draw itself at the location of the rectangle (if the NSImage is not scalable).

public boolean drawRepresentationInRect(NSImageRep imageRep, NSRect dstRect)

Discussion

The rectangle is located in the current window and is specified in the current coordinate system. This method returns the value returned by the drawInRect or drawAtPoint method, which indicates whether or not the representation was successfully drawn.

This method shouldn’t be called directly; the NSImage uses it to cache and print its representations. By overriding it in a subclass, you can change how representations appear in the cache and thus how they’ll appear when composited. For example, your version of the method could scale or rotate the coordinate system, then send a message to super to perform this version.

If the background color is fully transparent and the image isn’t being cached by the NSImage, the rectangle won’t be filled before the representation draws.

isCachedSeparately

Returns true if each representation of the receiver is cached separately in an offscreen window of its own and false if they can be cached in offscreen windows together with other images.

public boolean isCachedSeparately()

Discussion

A return of false doesn’t mean that the windows are, in fact, shared, just that they can be. The default is false.

isDataRetained

Returns true if the receiver retains the data needed to render the image and false if it doesn’t.

public boolean isDataRetained()

Discussion

The default is false. If the data is available 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 NSImage to retain the data.

isFlipped

Returns true if a vertically flipped coordinate system is used when locating the position of the receiver and false if it isn’t.

public boolean isFlipped()

Discussion

The default is false.

See Also

isValid

Returns true if a representation for the receiver can drawn in the cache and false if it can’t—for example, because the file from which it was initialized is nonexistent, or the data in that file is invalid.

public boolean isValid()

Discussion

If no representations exist for the receiver, isValid first creates a cache with the default depth.

lockFocus

Prepares the current device for drawing the receiver by setting the offscreen window (where the receiver’s representation will be cached) as the current window. It also sets the coordinate system of the offscreen window’s relevant area to the current coordinate system.

public void lockFocus()

Discussion

If the receiver has no representations, lockFocus first creates one with the default depth. See “How an Image Representation Is Chosen” for information on how the “best” representation is chosen.

A successful lockFocus message must be balanced by a subsequent unlockFocus message to the same NSImage. These messages bracket the code that draws the image.

If lockFocus is unable to focus on the representation, it throws an ImageCacheException.

See Also

lockFocusOnRepresentation

Prepares the current device for drawing the imageRepresentation receiver by setting the offscreen window (where the representation will be cached) as the current window. It also sets the coordinate system of the offscreen window’s relevant area to the current coordinate system.

public void lockFocusOnRepresentation(NSImageRep imageRepresentation)

Discussion

If imageRepresentation is null, lockFocusOnRepresentation acts like lockFocus, setting focus to the best representation for the NSImage. Otherwise, imageRepresentation must be one of the representations in the NSImage.

A successful lockFocusOnRepresentation message must be balanced by a subsequent unlockFocus message to the same NSImage. These messages bracket the code that draws the image.

If lockFocusOnRepresentation is unable to focus on the representation, it throws an ImageCacheException.

See Also

matchesOnMultipleResolution

Returns true if the resolution of the device and the resolution specified for the image are considered to match if one is an integer multiple of the other, and false if device and image resolutions are considered to match only if they are exactly the same.

public boolean matchesOnMultipleResolution()

Discussion

The default is true.

See Also

name

Returns the name assigned to the receiver, or null if no name has been assigned.

public String name()

See Also

prefersColorMatch

public boolean prefersColorMatch()

Discussion

Returns true if, when selecting the representation it will use, the receiver first looks for one that matches the color capability of the rendering device (choosing a grayscale 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 false, the NSImage 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 true.

See Also

recache

Invalidates the offscreen caches of all representations and frees them.

public void recache()

Discussion

The next time any representation is composited, it will first be asked to redraw itself in the cache. NSCachedImageReps 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 the amount of memory consumed by your program and therefore improve performance. If you modify an image represenation of an NSImage object, you must send recache to the image object to have the changed representation redrawn and recached.

removeRepresentation

Removes and releases the imageRep representation from the receiver’s list of representations.

public void removeRepresentation(NSImageRep imageRep)

See Also

representations

Returns an array containing all the representations of the receiver.

public NSArray representations()

scalesWhenResized

public boolean scalesWhenResized()

Discussion

Returns true if image representations are scaled to fit the size specified for the receiver. If representations are not scalable, this method returns false. The default is false.

Representations created from data that specifies a size (for example, the “ImageLength” and “ImageWidth” fields of a TIFF representation or the bounding box of an EPS representation) will have the size the data specifies, which may differ from the size of the NSImage.

See Also

setBackgroundColor

Sets the background color of the image.

public void setBackgroundColor(NSColor aColor)

Discussion

The default is NSColor’s clearColor, indicating a 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 caches are always created with a white background. This method doesn’t cause the receiver to recache itself.

See Also

setCacheDepthMatchesImageDepth

Sets whether the application’s default depth limit applies to the offscreen windows where the receiver’s representations are cached.

public void setCacheDepthMatchesImageDepth(boolean flag)

Discussion

If flag is true, window depths are determined by the specifications of the representations. If flag is false (the default), the application’s default depth limit applies to the off-screen windows where the receiver’s representations are cached. This method doesn’t cause the receiver to recache itself.

See Also

setCachedSeparately

Sets whether each image representation will be cached in its own offscreen window or in a window shared with other images.

public void setCachedSeparately(boolean flag)

Discussion

If flag is true, each representation is guaranteed to be in a separate window. If flag is false (the default), a representation can be cached together with other images, though in practice it might not be.

If an NSImage is to be resized frequently, it’s more efficient to cache its representations separately.

This method doesn’t invalidate any existing caches.

See Also

setCacheMode

Set the receiver’s caching mode.

public void setCacheMode(int mode)

Discussion

Possible values for mode are described in “Constants.”

Availability
See Also

setDataRetained

Sets whether the receiver retains the data needed to render the image, depending on the Boolean value flag.

public void setDataRetained(boolean flag)

Discussion

The default is false. If the data is available 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 receiver to retain the data. However, if the receiver reads image data from a file that could change, you may want to have it keep the data itself. Generally, this method is useful to redraw the image to a device of different resolution.

setDelegate

Makes anObject the delegate of the receiver.

public void setDelegate(Object anObject)

See Also

setFlipped

Determines whether the polarity of the y axis is inverted when drawing an image.

public void setFlipped(boolean flag)

Discussion

If flag is true, 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; it doesn’t affect the coordinate system for specifying portions of the image for methods like compositeToPointFromRect or dissolveToPointFromRect. This method doesn’t cause the receiver to recache itself.

If the image is cached while flag is true, then the receiver is cached flipped and changing flag does not affect the orientation of the cached image.

See Also

setMatchesOnMultipleResolution

Sets whether image representations with resolutions that are integral multiples of the resolution of the device are considered to match the device, depending on the Boolean value flag.

public void setMatchesOnMultipleResolution(boolean flag)

Discussion

The default is true.

See Also

setName

Registers the receiver under the name specified by aString, provided that no other NSImage is registered using that name.

public boolean setName(String aString)

Discussion

If the receiver is already registered under another name, setName first unregisters the prior name. setName returns true unless another NSImage is registered using the name specified by aString, in which case setName does nothing and returns false.

See Also

setPrefersColorMatch

Sets whether color matches are preferred over resolution matches when determining which representation to use.

public void setPrefersColorMatch(boolean flag)

Discussion

If flag is true, the receiver 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 false, the NSImage 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 true.

See Also

setScalesWhenResized

Sets whether representations with sizes that differ from the size of the receiver will be scaled to fit.

public void setScalesWhenResized(boolean flag)

Discussion

If flag is true, representations are scaled to fit. The default is false.

A representation added with either addRepresentation or addRepresentations may have a different size, and representations created from data that specifies a size (for example, the “ImageLength” and “ImageWidth” fields of a TIFF representation or the bounding box of an EPS representation) will have the size specified.

This method doesn’t cause the receiving NSImage to recache itself when it is next composited.

See Also

setSize

Sets the width and height of the image.

public void setSize(NSSize aSize)

Discussion

aSize should be in units of the base coordinate system.

The size of an NSImage must be set before it can be used. You can change the size of an NSImage after it has been used, but changing it invalidates all its caches and frees them. When the image is next composited, the selected representation will draw itself in an offscreen window to recreate the cache.

If the size of the image hasn’t already been set when the NSImage is provided with a representation, the size will be set from the data. The bounding box is used to determine the size of an NSEPSImageRep. The TIFF fields “ImageLength” and “ImageWidth” are used to determine the size of an NSBitmapImageRep.

See Also

setUsesEPSOnResolutionMismatch

Sets whether EPS representations are preferred when there are no representations that match the resolution of the device, depending on the Boolean value flag.

public void setUsesEPSOnResolutionMismatch(boolean flag)

Discussion

The default is false.

See Also

size

Returns the size of the receiver.

public NSSize size()

Discussion

If no size has been set, and no size can be determined from any of the receiver’s representations, the returned NSSize will have a width and height of 0.0.

See Also

TIFFRepresentation

Returns a data object containing TIFF for all representations, using their default compressions.

public NSData TIFFRepresentation()

Returns a data object containing TIFF for all representations, using the specified compression type and compression factor.

public NSData TIFFRepresentation(int comp, float aFloat)

Discussion

Legal values for comp are described in “TIFF Compression in NSBitmapImageReps”. aFloat provides a hint for those compression types that implement variable compression ratios; currently only JPEG compression uses a compression factor.

If the specified compression isn’t applicable, no compression is used. If a problem is encountered during generation of the TIFF, TIFFRepresentation throws an exception.

See Also

unlockFocus

Balances a previous lockFocus or lockFocusOnRepresentation message.

public void unlockFocus()

Discussion

All successful lockFocus and lockFocusOnRepresentation messages (those that don’t throw an ImageCacheException) must be followed by a subsequent unlockFocus message. Those that throw should never be followed by unlockFocus.

usesEPSOnResolutionMismatch

Returns whether EPS representations are preferred when there are no representations that match the resolution of the device.

public boolean usesEPSOnResolutionMismatch()

Discussion

The default is false.

See Also

Constants

The following compositing operators are defined by NSImage and used by compositeToPointFromRect, compositeToPoint, compositeToPointFromRectWithFraction, compositeToPointWithFraction, drawAtPoint, and drawInRect.

The constants are described in terms of having source and destination images, each having an opaque and transparent region. The destination image after the operation is defined in terms of the source and destination before images as follows:

Constant

Description

CompositeClear

Transparent.

CompositeCopy

Source image.

CompositeDestinationAtop

Destination image wherever both images are opaque, source image wherever source image is opaque but destination image is transparent, and transparent elsewhere.

CompositeDestinationIn

Destination image wherever both images are opaque, and transparent elsewhere.

CompositeDestinationOut

Destination image wherever destination image is opaque but source image is transparent, and transparent elsewhere.

CompositeDestinationOver

Destination image wherever destination image is opaque, and source image elsewhere.

CompositeHighlight

Deprecated. Mapped to CompositeSourceOver.

CompositePlusDarker

Sum of source and destination images, with color values approaching 0 as a limit.

CompositePlusLighter

Sum of source and destination images, with color values approaching 1 as a limit.

CompositeSourceAtop

Source image wherever both images are opaque, destination image wherever destination image is opaque but source image is transparent, and transparent elsewhere.

CompositeSourceIn

Source image wherever both images are opaque, and transparent elsewhere.

CompositeSourceOut

Source image wherever source image is opaque but destination image is transparent, and transparent elsewhere.

CompositeSourceOver

Source image wherever source image is opaque, and destination image elsewhere.

CompositeXOR

Exclusive OR of source and destination images. Works only with black and white images and is not recommended for color contexts.

The following constants are status values passed to the incremental loading delegate method imageDidLoadRepresentation.

Constant

Description

ImageLoadStatusCompleted

Enough data has been provided to completely decompress the image.

ImageLoadStatusCancelled

Image loading was canceled. The image contains the portions of the data that have already been successfully decompressed, if any.

ImageLoadStatusInvalidData

An error occurred during image decompression. The image data is probably corrupt. The image contains the portions of the data that have already been successfully decompressed, if any.

ImageLoadStatusUnexpectedEOF

Not enough data was available for full decompression of the image. The image contains the portions of the data that have already been successfully decompressed, if any.

ImageLoadStatusReadError

Not enough data was available for full decompression of the image. The image contains the portions of the data that have already been successfully decompressed, if any.

The follow constants specify the caching policy on a per NSImage basis. The caching policy is set using cacheMode and setCacheMode.

Constant

Description

ImageCacheDefault

Caching is unspecified. Use the image rep's default.

ImageCacheAlways

Always generate a cache when drawing.

ImageCacheBySize

Cache if cache size is smaller than the original data.

ImageCacheNever

Never cache; always draw direct.

For the various types of image reps, the default caching policy is:

Image Rep Class

Default caching policy

NSBitmapImageRep

ImageCacheBySize. Cache if bitmap is 32-bits in 16-bit world or greater than 72 dpi.

NSPICTImageRep

ImageCacheBySize. Same reasoning as NSBitmapImageRep in the event the PICT contains a bitmap.

NSPDFImageRep

ImageCacheAlways

Delegate Methods

imageDidLoadPartOfRepresentation

During incremental loading, this method is called repeatedly to inform the delegate that more of the image rep is available.

public abstract void imageDidLoadPartOfRepresentation(NSImage image, NSImageRep rep, int rows)

Discussion

This method is optional; incremental loading will continue if the delegate does not implement it.

Availability

imageDidLoadRepresentation

This method is invoked when image has been as fully decompressed as is possible.

public abstract void imageDidLoadRepresentation(NSImage image, NSImageRep rep, int status)

Discussion

The image invokes this method on the delegate to notify it that the NSImageRep rep has finished downloading with a final status of status.

If an error occurs during downloading or decompression, status will be ImageLoadStatusInvalidData, ImageLoadStatusUnexpectedEOF, or ImageLoadStatusReadError. If you cancel the download, status will be ImageLoadStatusCancelled.

This method is required for incremental loading; the delegate must implement it if incremental loading is desired. You must also set up the instance to be loaded lazily, by initializing it using either Constructor that initializes a file or URL lazily.

Availability

imageDidLoadRepresentationHeader

During incremental loading, the image invokes this method once enough data has been read to determine the size of the image.

public abstract void imageDidLoadRepresentationHeader(NSImage image, NSImageRep rep)

Discussion

At this point, the NSBitmapImageRep rep is valid and has storage for the bitmap. The bitmap is filled with the image's background color. This method is optional; incremental loading will continue if the delegate does not implement it.

Availability

imageDidNotDraw

Implemented by the delegate to respond to a message sent by the sender (an NSImage) when the sender was unable, for whatever reason, to composite or lock focus on its image to draw in aRect.

public abstract NSImage imageDidNotDraw(Object sender, NSRect aRect)

Discussion

The delegate can do one of the following:

imageWillLoadRepresentation

For incremental loading, this method is invoked when you first draw image or otherwise require the bitmap data.

public abstract void imageWillLoadRepresentation(NSImage image, NSImageRep rep)

Discussion

The image download begins immediately after this method returns. This method is optional; incremental loading will continue if the delegate does not implement it.

Availability


Next Page > Hide TOC

© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.