Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/AppKit.framework |
Availability | Available in Mac OS X v10.0 and later. |
Companion guide | |
Declared in | NSGraphics.h NSImage.h |
An NSImage
object is a high-level class for manipulating image data. You use this class to load existing images or create new ones and composite them into a view or other image. This class works in conjunction with one or more image representation objects (subclasses of NSImageRep
), which manage the actual image data.
– initByReferencingFile:
– initByReferencingURL:
– initWithCGImage:size:
– initWithContentsOfFile:
– initWithContentsOfURL:
– initWithData:
– initWithDataIgnoringOrientation:
– initWithPasteboard:
– initWithSize:
– initWithIconRef:
+ canInitWithPasteboard:
+ imageTypes
+ imageUnfilteredTypes
+ imageFileTypes
+ imageUnfilteredFileTypes
+ imagePasteboardTypes
+ imageUnfilteredPasteboardTypes
– addRepresentation:
– addRepresentations:
– representations
– removeRepresentation:
– bestRepresentationForRect:context:hints:
– bestRepresentationForDevice:
Deprecated in Mac OS X v10.6
– setPrefersColorMatch:
– prefersColorMatch
– setUsesEPSOnResolutionMismatch:
– usesEPSOnResolutionMismatch
– setMatchesOnMultipleResolution:
– matchesOnMultipleResolution
– lockFocus
– lockFocusFlipped:
– unlockFocus
– lockFocusOnRepresentation:
Deprecated in Mac OS X v10.6
– drawAtPoint:fromRect:operation:fraction:
– drawInRect:fromRect:operation:fraction:
– drawRepresentation:inRect:
– drawInRect:fromRect:operation:fraction:respectFlipped:hints:
– compositeToPoint:fromRect:operation:
Deprecated in Mac OS X v10.6
– compositeToPoint:fromRect:operation:fraction:
Deprecated in Mac OS X v10.6
– compositeToPoint:operation:
Deprecated in Mac OS X v10.6
– compositeToPoint:operation:fraction:
Deprecated in Mac OS X v10.6
– dissolveToPoint:fraction:
Deprecated in Mac OS X v10.6
– dissolveToPoint:fromRect:fraction:
Deprecated in Mac OS X v10.6
– cacheMode
– setCacheMode:
– cacheDepthMatchesImageDepth
Deprecated in Mac OS X v10.6
– isCachedSeparately
Deprecated in Mac OS X v10.6
– isDataRetained
Deprecated in Mac OS X v10.6
– setCacheDepthMatchesImageDepth:
Deprecated in Mac OS X v10.6
– setCachedSeparately:
Deprecated in Mac OS X v10.6
– setDataRetained:
Deprecated in Mac OS X v10.6
– isValid
– setBackgroundColor:
– backgroundColor
– recache
– isFlipped
Deprecated in Mac OS X v10.6
– scalesWhenResized
Deprecated in Mac OS X v10.6
– setFlipped:
Deprecated in Mac OS X v10.6
– setScalesWhenResized:
Deprecated in Mac OS X v10.6
Tests whether the receiver can create an instance of itself using pasteboard data.
+ (BOOL)canInitWithPasteboard:(NSPasteboard *)pasteboard
The pasteboard containing the image data.
YES
if the receiver knows how to handle the data on the pasteboard; otherwise, NO
.
This method uses the NSImageRep
class method imageUnfilteredPasteboardTypes
to find a class that can handle the data in the specified pasteboard. If you create your own NSImageRep
subclasses, override the imageUnfilteredPasteboardTypes
method to notify NSImage
of the pasteboard types your class supports.
NSImage.h
Returns an array of strings identifying the image types supported by the registered NSImageRep
objects.
+ (NSArray *)imageFileTypes
An array of NSString
objects, each of which identifies a single supported file type. The array can include encoded HFS file types as well as filename extensions.
This list includes all file types supported by registered subclasses of NSImageRep
plus those that can be converted to a supported type by a user-installed filter service. You can pass the array returned by this method directly to the runModalForTypes:
method of NSOpenPanel
.
When creating a subclass of NSImageRep
, do not override this method. Instead, override the imageUnfilteredFileTypes
method to notify NSImage
of the file types your class supports directly.
NSImage.h
Returns the NSImage
instance associated with the specified name.
+ (id)imageNamed:(NSString *)name
The name associated with the desired image.
The NSImage
object associated with the specified name, or nil
if no such image was found.
This method searches for named images in several places, returning the first image it finds matching the given name. The order of the search is as follows:
Search for an object whose name was set explicitly using the setName: method and currently resides in the image cache.
Search the application's main bundle for a file whose name matches the specified string. (For information on how the bundle is searched, see ““Accessing a Bundle's Contents”“ in Bundle Programming Guide.)
Search the Application Kit framework for a shared image with the specified name.
When looking for files in the application bundle, it is better (but not required) to include the filename extension in the name
parameter. When naming an image with the setName: method, it is also convention not to include filename extensions in the names you specify. That way, you can easily distinguish between images you have named explicitly and those you want to load from the application's bundle.
One particularly useful image you can retrieve is your application's icon. This image is set by Cocoa automatically and referenced by the string @"NSApplicationIcon"
. Icons for other applications can be obtained through the use of methods declared in the NSWorkspace
class. You can also retrieve many of the standard system images using Cocoa defined constants; for more information, see the “Image Template Constants,” “Sharing Permissions Named Images,” “System Entity Images,” “Toolbar Named Images,” and “View Type Template Images” sections for applicable constants.
If an application is linked in Mac OS X v10.5 or later, images requested using this method and whose name ends in the word “Template” are automatically marked as template images.
The NSImage
class may cache a reference to the returned image object for performance in some cases. However, the class holds onto cached objects only while the object exists. If the image object is subsequently released, either because its retain count was 0 or it was not referenced anywhere in a garbage-collected application, the object may be quietly removed from the cache. Thus, if you plan to hold onto a returned image object, you must retain it like you would any Cocoa object. You can clear an image object from the cache explicitly by calling the object’s setName: method and passing nil
for the image name.
– setName:
– name
iconForFile:
(NSWorkspace)+ imageFileTypes
NSImage.h
Returns an array of strings identifying the pasteboard types supported directly by the registered NSImageRep
objects.
+ (NSArray *)imagePasteboardTypes
An array of NSString
objects, each of which identifies a single supported pasteboard type. By default, this list contains the NSPDFPboardType
, NSPICTPboardType
, NSPostScriptPboardType
, and NSTIFFPboardType
types.
This list includes all pasteboard types supported by registered subclasses of NSImageRep
plus those that can be converted to a supported type by a user-installed filter service.
When creating a subclass of NSImageRep
, do not override this method. Instead, override the imageUnfilteredPasteboardTypes
method to notify NSImage
of the pasteboard types your class supports.
NSImage.h
Returns an array of UTI strings identifying the image types supported by the registered NSImageRep
objects, either directly or through a user-installed filter service.
+ (NSArray *)imageTypes
An array of NSString
objects, each of which contains a UTI identifying a supported image type. Some sample image-related UTI strings include "public.image
”, "public.jpeg
”, and "public.tiff
”. For a list of supported types, see UTCoreTypes.h
.
The returned list includes UTIs all file types supported by registered subclasses of NSImageRep
plus those that can be converted to a supported type by a user-installed filter service. You can use the returned UTI strings with any method that supports UTIs.
You should not override this method directly. Instead, you should override the imageTypes
method of NSImageRep
.
NSImage.h
Returns an array of strings identifying the file types supported directly by the registered NSImageRep
objects.
+ (NSArray *)imageUnfilteredFileTypes
An array of NSString
objects, each of which identifies a single supported file type. File types are identified by file extension and HFS file types.
The returned list does not contain pasteboard types that are available only through a user-installed filter service.
NSImage.h
Returns an array of strings identifying the pasteboard types supported directly by the registered NSImageRep
objects.
+ (NSArray *)imageUnfilteredPasteboardTypes
An array of NSString
objects, each of which identifies a single supported pasteboard type.
The returned list does not contain pasteboard types that are supported only through a user-installed filter service.
NSImage.h
Returns an array of UTI strings identifying the image types supported directly by the registered NSImageRep
objects.
+ (NSArray *)imageUnfilteredTypes
An array of NSString
objects, each of which contains a UTI identifying a supported image type. Some sample image-related UTI strings include "public.image
”, "public.jpeg
”, and "public.tiff
”. For a list of supported types, see UTCoreTypes.h
.
The returned list includes UTI strings only for those file types that are supported directly by registered subclasses of NSImageRep
. It does not include types that are supported through user-installed filter services. You can use the returned UTI strings with any method that supports UTIs.
You should not override this method directly. Instead, you should override the imageUnfilteredTypes
method of NSImageRep
.
NSImage.h
Returns the image’s accessibility description.
- (NSString *)accessibilityDescription
A short localized string that does not include the name of the interface element.
NSImage.h
Adds the specified image representation object to to the receiver.
- (void)addRepresentation:(NSImageRep *)imageRep
The image representation to add.
After invoking this method, you may need to explicitly set features of the new image representation, such as the size, number of colors, and so on. This is true particularly when the NSImage
object 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 receiver. Image representations cannot be shared among multiple NSImage
objects.
NSImage.h
Adds an array of image representation objects to the receiver.
- (void)addRepresentations:(NSArray *)imageReps
An array of NSImageRep
objects.
After invoking this method, you may need to explicitly set features of the new image representations, such as their size, number of colors, and so on. This is true particularly when the NSImage
object 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 receiver. Image representations cannot be shared among multiple NSImage
objects.
NSImage.h
Returns alignment metadata that your code can use to position the image during layout.
- (NSRect)alignmentRect
A rectangle containing the layout information for the image. If not set, the returned rectangle has an origin of (0, 0) and a size that matches the size of the image.
The returned rectangle is merely a hint that your own code can use to determine positioning. The NSImage
class does not use this rectangle during drawing. However, instances of NSCell
typically use this information when laying out images within their own boundaries.
NSImage.h
Returns the background color of image.
- (NSColor *)backgroundColor
The background color of the image. The default color is transparent, as returned by the clearColor
method of NSColor
.
The background color is visible only if the drawn image representation does not completely cover all of the pixels available for the image's current size.
NSImage.h
Returns the best representation of the image for the specified rect using the provided hints.
- (NSImageRep *)bestRepresentationForRect:(NSRect)rect context:(NSGraphicsContext *)referenceContext hints:(NSDictionary *)hints
The area of the image to return.
A graphics context. This value can be nil
.
An optional dictionary of hints that provide more context for selecting or generating a CGImage
, and may override properties of the referenceContext. See “Image Hint Dictionary Keys” for a summary of the possible key-value pairs.
The image representation that most closely matches the specified criteria.
NSImage.h
Returns the receiver’s caching mode.
- (NSImageCacheMode)cacheMode
A value indicating the caching mode. For a list of possible values, see NSImageCacheMode
. This value is set to NSImageCacheDefault
by default.
NSImage.h
Cancels the current download operation immediately, if the image is being incrementally loaded.
- (void)cancelIncrementalLoad
This call has no effect if the image is not loading.
NSImage.h
Returns a CGImage
capturing the drawing of the receiver.
- (CGImageRef)CGImageForProposedRect:(NSRect *)proposedDestRect context:(NSGraphicsContext *)referenceContext hints:(NSDictionary *)hints
On input, the proposed destination rectangle for drawing the image. If NULL
, it defaults to the smallest pixel-integral rectangle containing {{0,0}, [self size]}. The proposedDestRect is in user space in the reference context.
A graphics context.
A dictionary of hints that provide more context for selecting or generating a CGImage
, and may override properties of the referenceContext.
A CGImageRef
. This may be an existing CGImage
if one is available. If not, a new CGImage
is created.
An NSImage
is potentially resolution independent, and may have representations that allow it to draw well in many contexts. A CGImage
is more like a single pixel-based representation. This method produces a snapshot of how the NSImage
would draw if it was asked to draw in the proposed rectangle in the graphics context.
All input parameters are optional. They provide hints for how to choose among existing CGImages, or how to create one if there isn't already a CGImage available. The parameters are only hints.
This method is typically called, not overridden.
NSImage.h
Returns the delegate object of the receiver
- (id < NSImageDelegate >)delegate
The current delegate object, or nil
if no delegate has been set.
NSImage.h
Draws all or part of the image at the specified point in the current coordinate system.
- (void)drawAtPoint:(NSPoint)point fromRect:(NSRect)srcRect operation:(NSCompositingOperation)op fraction:(CGFloat)delta
The location in the current coordinate system at which to draw the image.
The source rectangle specifying the portion of the image you want to draw. The coordinates of this rectangle are specified in the image's own coordinate system. If you pass in NSZeroRect
, the entire image is drawn.
The compositing operation to use when drawing the image. See the NSCompositingOperation
constants.
The opacity of the image, specified as a value from 0.0 to 1.0. Specifying a value of 0.0 draws the image as fully transparent while a value of 1.0 draws the image as fully opaque. Values greater than 1.0 are interpreted as 1.0.
The image content is drawn at its current resolution and is not scaled unless the CTM of the current coordinate system itself contains a scaling factor. The image is otherwise positioned and oriented using the current coordinate system.
Unlike the compositeToPoint:fromRect:operation:
and compositeToPoint:fromRect:operation:fraction:
methods, this method checks the rectangle you pass to the srcRect parameter and makes sure it does not lie outside the image bounds.
NSImage.h
Draws all or part of the image in the specified rectangle in the current coordinate system.
- (void)drawInRect:(NSRect)dstRect fromRect:(NSRect)srcRect operation:(NSCompositingOperation)op fraction:(CGFloat)delta
The rectangle in which to draw the image, specified in the current coordinate system.
The source rectangle specifying the portion of the image you want to draw. The coordinates of this rectangle must be specified using the image's own coordinate system. If you pass in NSZeroRect
, the entire image is drawn.
The compositing operation to use when drawing the image. See the NSCompositingOperation
constants.
The opacity of the image, specified as a value from 0.0 to 1.0. Specifying a value of 0.0 draws the image as fully transparent while a value of 1.0 draws the image as fully opaque. Values greater than 1.0 are interpreted as 1.0.
If the srcRect
and dstRect
rectangles have different sizes, the source portion of the image is scaled to fit the specified destination rectangle. The image is otherwise positioned and oriented using the current coordinate system.
Unlike the compositeToPoint:fromRect:operation:
and compositeToPoint:fromRect:operation:fraction:
methods, this method checks the rectangle you pass to the srcRect parameter and makes sure it does not lie outside the image bounds.
NSImage.h
Draws all or part of the image in the specified rectangle respecting the flippedness and hints.
- (void)drawInRect:(NSRect)dstSpacePortionRect fromRect:(NSRect)srcSpacePortionRect operation:(NSCompositingOperation)op fraction:(CGFloat)requestedAlpha respectFlipped:(BOOL)respectContextIsFlipped hints:(NSDictionary *)hints
The rectangle in which to draw the image, specified in the current coordinate system.
The source rectangle specifying the portion of the image you want to draw. The coordinates of this rectangle must be specified using the image's own coordinate system. If you pass in NSZeroRect
, the entire image is drawn.
The compositing operation to use when drawing the image. See the NSCompositingOperation
constants.
The alpha of the image, specified as a value from 0.0 to 1.0. Specifying a value of 0.0 draws the image as fully transparent while a value of 1.0 draws the image as fully opaque. Values greater than 1.0 are interpreted as 1.0.
YES
if the drawing should respect the context flipped state, otherwise NO
.
An optional dictionary of hints that provide more context for selecting or generating the image. See “Image Hint Dictionary Keys” for a summary of the possible key-value pairs.
If the srcSpacePortionRect and dstSpacePortionRect rectangles have different sizes, the source portion of the image is scaled to fit the specified destination rectangle.
NSImage.h
Draws the image using the specified image representation object.
- (BOOL)drawRepresentation:(NSImageRep *)imageRep inRect:(NSRect)dstRect
The image representation object to be drawn.
The rectangle in which to draw the image representation, specified in the current coordinate system.
YES
if the image was successfully drawn; otherwise, returns NO
.
This method fills the specified rectangle with the image's current background color and then sends a message to the specified image representation asking if to draw itself. If the image supports the ability to scale itself when it is resized, this method sends a drawInRect:
message; otherwise, it sends a drawAtPoint:
message.
You should not call this method directly; an NSImage
object uses it to cache and print its image representations. You can override this method to change the way images are rendered into their caches and onto the printed page. For example, you could scale or rotate the coordinate system before sending this message to super
to continue rendering the image representation.
If the background color is fully transparent and the image data is not being cached, the specified rectangle is not to be filled before the representation draws.
NSImage.h
Returns whether the destination rectangle would intersect a non-transparent portion of the image.
- (BOOL)hitTestRect:(NSRect)testRectDestSpacewithImageDestinationRect:(NSRect)imageRectDestSpacecontext:(NSGraphicsContext *)referenceContexthints:(NSDictionary *)hintsflipped:(BOOL)flipped
The rectangle to hit test.
A rectangle representing the drawn size of the image.
A graphics context. This value can be nil
.
An optional dictionary of hints that provide more context for selecting or generating a CGImage
, and may override properties of the referenceContext. See “Image Hint Dictionary Keys” for a summary of the possible key-value pairs.
YES
if the image is flipped, otherwise NO
.
YES if the testRectDestSpace intersects with non-transparent content within the imageRectDestSpace, otherwise NO.
This method simulates the results of hit-testing the test rectangle as if the image was drawn in the graphics context using the provided hints and respecting the specified flippedness..
NSImage.h
Initializes and returns an NSImage
instance and associates it with the specified file.
- (id)initByReferencingFile:(NSString *)filename
A full or relative path name specifying the file with the desired image data. Relative paths must be relative to the current working directory.
An initialized NSImage
instance, or nil
if the new instance cannot be initialized.
This method initializes the image object lazily. It does not actually open the specified file or create any image representations from its data until an application attempts to draw the image or request information about it.
The filename parameter should include the file extension that identifies the type of the image data. The mechanism that actually creates the image representation for filename looks for an NSImageRep
subclass that handles that data type from among those registered with NSImage
.
Because this method doesn’t actually create image representations for the image 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 YES
, thus enabling it to hold onto its filename. When archiving an image created with this method, only the image's filename is written to the archive.
If the cached version of the image uses less memory than the original image data, the original data is flushed and the cached image is used. (This can occur for images whose resolution is greater than 72 dpi.) If you resize the image by less than 50%, the data is loaded in again from the file. If you expect the file to change or be deleted, you should use initWithContentsOfFile:
instead.
NSImage.h
Initializes and returns an NSImage
instance and associates it with the specified URL.
- (id)initByReferencingURL:(NSURL *)url
The URL identifying the image.
An initialized NSImage
instance, or nil
if the new instance cannot be initialized.
This method initializes the image object lazily. It does not attempt to retrieve the data from the specified URL or create any image representations from that data until an application attempts to draw the image or request information about it.
This url
parameter should include a file extension that identifies the type of the image data. The mechanism that actually creates the image representation looks for an NSImageRep
subclass that handles that data type from among those registered with NSImage
.
Because this method doesn’t actually create image representations for the image 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 YES
, thus enabling it to hold onto its URL. When archiving an image created with this method, only the image's URL is written to the archive.
NSImage.h
Initializes and returns an NSImage
instance with the contents of the CGImage.
- (id)initWithCGImage:(CGImageRef)cgImagesize:(NSSize)size
The source CGImage
.
The size of the new image. If size is NSZeroSize
, the pixel dimensions of cgImage are assumed as the image’s size.
An initialized NSImage
instance, or nil
if the new instance cannot be initialized.
You should not assume anything about the image, other than that drawing it is equivalent to drawing the CGImage
.
This is not a designated initializer.
NSImage.h
Initializes and returns an NSImage
instance with the contents of the specified file.
- (id)initWithContentsOfFile:(NSString *)filename
A full or relative path name specifying the file with the desired image data. Relative paths must be relative to the current working directory.
An initialized NSImage
instance, or nil
if the method cannot create an image representation from the contents of the specified file.
Unlike initByReferencingFile:
, which initializes an NSImage
object lazily, this method immediately opens the specified file and creates one or more image representations from its data.
The filename parameter should include the file extension that identifies the type of the image data. This method looks for an NSImageRep
subclass that handles that data type from among those registered with NSImage
.
NSImage.h
Initializes and returns an NSImage
instance with the contents of the specified URL.
- (id)initWithContentsOfURL:(NSURL *)aURL
The URL identifying the image.
An initialized NSImage
instance, or nil
if the method cannot create an image representation from the contents of the specified URL.
NSImage.h
Initializes and returns an NSImage
instance with the contents of the specified NSData
object.
- (id)initWithData:(NSData *)data
The data object containing the image data.
An initialized NSImage
instance, or nil
if the method cannot create an image representation from the contents of the specified data object.
NSImage.h
Initializes and returns an NSImage
instance with the contents of the specified NSData
object, ignoring the EXIF orientation tags..
- (id)initWithDataIgnoringOrientation:(NSData *)data
The data object containing the image data.
An initialized NSImage
instance, or nil
if the method cannot create an image representation from the contents of the specified data object.
NSImage.h
Initializes the image object with a Carbon-style icon resource.
- (id)initWithIconRef:(IconRef)iconRef
A reference to a Carbon icon resource.
An initialized NSImage
instance.
Creates one or more bitmap image representations, one for each size icon contained in the IconRef
data structure. This initialization method automatically retains the data in the iconRef
parameter and loads the bitmaps from that data file lazily.
NSImage.h
Initializes and returns an NSImage
instance with data from the specified pasteboard.
- (id)initWithPasteboard:(NSPasteboard *)pasteboard
The pasteboard containing the image data.
An initialized NSImage
instance, or nil
if the method cannot create an image representation from the contents of the pasteboard.
The specified pasteboard should contain a type supported by one of the registered NSImageRep
subclasses. Table 1 lists the default pasteboard types and file extensions for several NSImageRep
subclasses.
Image representation class | Default pasteboard type | Default file extensions |
---|---|---|
|
| |
|
| |
|
|
|
|
|
If the specified pasteboard contains the value NSFilenamesPboardType
, each filename on the pasteboard should have an extension supported by one of the registered NSImageRep
subclasses. You can use the imageUnfilteredFileTypes
method of a given subclass to obtain the list of supported types for that class.
NSImage.h
Initializes and returns an NSImage
instance whose size is set to the specified value.
- (id)initWithSize:(NSSize)aSize
The size of the image, measured in points.
An initialized NSImage
instance.
This method does not add any image representations to the image object.. It is permissible to initialize the receiver by passing a size of (0.0, 0.0); however, the receiver’s size must be set to a non-zero value before the NSImage
object is used or an exception will be raised.
NSImage.h
Returns a Boolean value indicating whether the image is a template image.
- (BOOL)isTemplate
YES
if the image is a template image; otherwise, NO
.
Template images consist of black and clear colors (and an alpha channel). Template images are not intended to be used as standalone images and are usually mixed with other content to create the desired final appearance.
NSImage.h
Returns a Boolean value indicating whether an image representation from the receiver can be drawn.
- (BOOL)isValid
YES
if the receiver can be drawn; otherwise, NO
.
If the receiver is initialized with an existing image file, but the corresponding image data is not yet loaded into memory, this method loads the data and expands it as needed. If the receiver contains no image representations and no associated image file, this method creates a valid cached image representation and initializes it to the default bit depth. This method returns NO
in cases where the file or URL from which it was initialized is nonexistent or when the data in an existing file is invalid.
NSImage.h
Prepares the image to receive drawing commands.
- (void)lockFocus
This method sets the current drawing context to the area of the offscreen window used to cache the receiver's contents. Subsequent drawing commands are composited to this offscreen window. If the offscreen drawing area already has some content, any new drawing commands are composited with that content. This method does not modify the original image data directly.
When locking focus, this method chooses the best image representation object available and locks focus on that object. If the receiver has no image representations, this method creates one with the default depth and locks focus on it. For information on how the "best" representation is chosen, see the “Images” chapter of Cocoa Drawing Guide.
A successful lockFocus
message must be balanced with a matching unlockFocus
message to the same NSImage
object. These messages bracket the code that draws the image.
If lockFocus
is unable to focus on the image, it raises an NSImageCacheException
.
NSImage.h
Prepares the image to receive drawing commands using the specified flipped state.
- (void)lockFocusFlipped:(BOOL)flipped
YES
if the drawing context should be flipped, otherwise NO
.
NSImage.h
Returns a Boolean value indicating whether image representations whose resolution is an integral multiple of the device resolution are considered a match.
- (BOOL)matchesOnMultipleResolution
YES
if image representations whose resolution is an integral multiple of the device resolution are considered a match; otherwise, NO
.
When this method returns NO
, only image representations whose resolution is exactly the same as the device resolution are considered matches. If this method returns YES
and multiple image representations fit this criteria, the one whose resolution is closest to the device resolution is chosen.
The default value is YES
.
NSImage.h
Returns the name associated with the receiver, if any.
- (NSString *)name
The name associated with the receiver, or nil
if no name is assigned.
NSImage.h
Returns a Boolean value indicating whether the image prefers to choose image representations using color matching or resolution matching.
- (BOOL)prefersColorMatch
YES
if color matching is preferred over resolution matching; otherwise NO
if resolution matching is preferred.
Both color matching and resolution matching may influence the choice of an image representation. This method simply indicates which technique is used first during the selection process. The default value is YES
.
NSImage.h
Invalidates and frees the offscreen caches of all image representations.
- (void)recache
If you modify an image representation, you must send a recache
message to the corresponding image object to force the changes to be recached. The next time any image representation is drawn, it is asked to recreate its cached image. If you do not send this message, the image representation may use the old cache data. This method simply clears the cached image data; it does not delete the NSCachedImageRep
objects associated with any image representations.
If you do not plan to use an image again right away, you can free its caches to reduce the amount of memory consumed by your program.
NSImage.h
Removes the specified image representation from the receiver and releases it.
- (void)removeRepresentation:(NSImageRep *)imageRep
The image representation object you want to remove.
NSImage.h
Returns an array containing all of the receiver's image representations.
- (NSArray *)representations
An array containing zero or more NSImageRep
objects.
NSImage.h
Sets the image’s accessibility description.
- (void)setAccessibilityDescription:(NSString *)description
A short localized string that does not include the name of the interface element.
This description will be used automatically by interface elements that display images. Like all accessibility descriptions, the string should be a short localized string that does not include the name of the interface element. For instance, "delete" rather than "delete button".
NSImage.h
Sets the alignment metadata that your code can use to position the image during layout.
- (void)setAlignmentRect:(NSRect)rect
The alignment rectangle for the image.
Alignment rectangles specify baselines that you can use to position the content of an image more accurately. These baselines are merely hints that your own code can use to determine positioning and are not used internally by NSImage
itself during drawing. For example, if you have a 20 x 20 pixel icon that includes a glow effect, you might set the alignment rectangle to {{2, 2}, {16, 16}} to indicate the position of the underlying icon without the glow effect.
NSImage.h
Sets the background color of the image.
- (void)setBackgroundColor:(NSColor *)aColor
The new background color for the image.
The background color is visible only if the drawn image representation does not completely cover all of the pixels available for the image's current size. The background color is ignored for cached image representations; such caches are always created with a white background. This method does not cause the receiver to recache itself.
NSImage.h
Set the receiver’s caching mode.
- (void)setCacheMode:(NSImageCacheMode)mode
The caching mode to use with this image. For a list of possible values, see NSImageCacheMode
.
The caching mode determines when the receiver's image representations use offscreen caches. Offscreen caches speed up rendering time but do so by using extra memory. In the default caching mode (NSImageCacheDefault
), each image representation chooses the caching technique that produces the fastest drawing times. For example, in the default mode, the NSPDFImageRep
and NSEPSImageRep
classes use the NSImageCacheAlways
mode but the NSBitmapImageRep
class uses the NSImageCacheBySize
mode.
For more information on image caching behavior, see the “Images” chapter of Cocoa Drawing Guide.
NSImage.h
Sets the delegate object of the receiver.
- (void)setDelegate:(id < NSImageDelegate >)anObject
The new delegate object.
NSImage.h
Sets whether image representations whose resolutions are integral multiples of the device resolution are considered a match.
- (void)setMatchesOnMultipleResolution:(BOOL)flag
YES
if image representations whose resolution is an integral multiple of the device resolution should be considered a match; otherwise, NO
.
NSImage.h
Registers the receiver under the specified name.
- (BOOL)setName:(NSString *)aString
The name to associate with the receiver.
YES
if the receiver was successfully registered with the given name; otherwise, NO
.
If the receiver is already registered under a different name, this method unregisters the other name. If a different image is registered under the name specified in aString, this method does nothing and returns NO
.
When naming an image using this method, it is convention not to include filename extensions in the names you specify. That way, you can easily distinguish between images you have named explicitly and those you want to load from the application's bundle. For information about the rules used to search for images, and for information about the ownership policy of named images, see the imageNamed: method.
NSImage.h
Sets whether choosing an image representation favors color matching over resolution matching.
- (void)setPrefersColorMatch:(BOOL)flag
YES
if the receiver should match the color capabilities of the rendering device first; otherwise, NO
to indicate that resolution matching is preferred.
Both color matching and resolution matching may influence the choice of an image representation. You use this method to choose which technique should be used first during the selection process.
NSImage.h
Sets the width and height of the image.
- (void)setSize:(NSSize)aSize
The new size of the image, measured in points.
The size of an NSImage
object must be set before it can be used. If the size of the image hasn’t already been set when an image representation is added, the size is taken from the image representation's data. For EPS images, the size is taken from the image's bounding box. For TIFF images, the size is taken from the ImageLength
and ImageWidth
attributes.
Changing the size of an NSImage
after it has been used effectively resizes the image. Changing the size 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.
NSImage.h
Sets whether the image represents a template image.
- (void)setTemplate:(BOOL)isTemplate
Specify YES
if the image is a template image; otherwise, NO
.
Images you mark as template images should consist of only black and clear colors. You can use the alpha channel in the image to adjust the opacity of black content, however.
Template images are not intended to be used as standalone images. They are always mixed with other content and processed to create the desired appearance. You can mark an image as a “template image” to notify clients who care that the image contains only black and clear content. The most common use for template images is in image cells. For example, you might use a template image to provide the content for a button or segmented control. Cocoa cells take advantage of the nature of template images—that is, their simplified color scheme and use of transparency—to improve the appearance of the corresponding control in each of its supported states.
NSImage.h
Sets whether EPS image representations are preferred when no other representations match the resolution of the device.
- (void)setUsesEPSOnResolutionMismatch:(BOOL)flag
YES
if EPS image representations are preferred; otherwise NO
.
NSImage.h
Returns the size of the receiver.
- (NSSize)size
The size of the receiver or (0.0, 0.0) if no size has been set and the size cannot be determined from any of the receiver's image representations.
NSImage.h
Returns a data object containing TIFF data for all of the image representations in the receiver.
- (NSData *)TIFFRepresentation
A data object containing the TIFF data, or nil
if the TIFF data could not be created.
You can use the returned data object to write the TIFF data to a file. For each image representation, this method uses the TIFF compression option associated with that representation or NSTIFFCompressionNone
, if no option is set.
If one of the receiver's image representations does not support the creation of TIFF data natively (PDF and EPS images, for example), this method creates the TIFF data from that representation's cached content.
Additional image formats can be saved by using the NSBitmapImageRep
method representationUsingType:properties:
.
– TIFFRepresentationUsingCompression:factor:
representationUsingType:properties:
(NSBitmapImageRep)TIFFRepresentation
(NSBitmapImageRep)TIFFRepresentationUsingCompression:factor:
(NSBitmapImageRep)NSImage.h
Returns a data object containing TIFF data with the specified compression settings for all of the image representations in the receiver.
- (NSData *)TIFFRepresentationUsingCompression:(NSTIFFCompression)comp factor:(float)aFloat
The type of compression to use. For a list of values, see the constants in NSBitmapImageRep
.
Provides a hint for compression types that implement variable compression ratios. Currently, only JPEG compression uses a compression factor.
A data object containing the TIFF data, or nil
if the TIFF data could not be created.
You can use the returned data object to write the TIFF data to a file. If the specified compression isn’t applicable, no compression is used. If a problem is encountered during generation of the TIFF data, this method may raise an exception.
If one of the receiver's image representations does not support the creation of TIFF data natively (PDF and EPS images, for example), this method creates the TIFF data from that representation's cached content.
Additional image formats can be saved by using the NSBitmapImageRep
method representationUsingType:properties:
.
– TIFFRepresentation
representationUsingType:properties:
(NSBitmapImageRep)TIFFRepresentation
(NSBitmapImageRep)TIFFRepresentationUsingCompression:factor:
(NSBitmapImageRep)NSImage.h
Removes the focus from the receiver.
- (void)unlockFocus
This message must be sent after a successful lockFocus
or lockFocusOnRepresentation:
message and the completion of any intermediate drawing commands. This method restores the focus to the previous owner, if any.
Do not send this message if the preceding call to lock focus raised an NSImageCacheException
.
NSImage.h
Returns a Boolean value indicating whether EPS representations are preferred when no other representations match the resolution of the device.
- (BOOL)usesEPSOnResolutionMismatch
YES
if EPS image representations are preferred; otherwise NO
.
The default value is NO
.
NSImage.h
These constants are a subset of the dictionary keys used in the hints dictionary for the methods CGImageForProposedRect:context:hints:
, bestRepresentationForRect:context:hints:
, drawInRect:fromRect:operation:fraction:respectFlipped:hints:
, and hitTestRect:withImageDestinationRect:context:hints:flipped:
. Additional hint keys are also valid including: Context Options
in CIContext
, and the entries in an NSScreen
device description dictionary as described in deviceDescription
.
NSString *const NSImageHintCTM; NSString *const NSImageHintInterpolation;
NSImageHintCTM
Provides a context transform hint. The value for this key is an NSAffineTransform
.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageHintInterpolation
Provides an interpolation hint. The value for this key is an NSNumber
with an NSImageInterpolation
value.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
These constants specify compositing operators 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.
enum { NSCompositeClear = 0, NSCompositeCopy = 1, NSCompositeSourceOver = 2, NSCompositeSourceIn = 3, NSCompositeSourceOut = 4, NSCompositeSourceAtop = 5, NSCompositeDestinationOver = 6, NSCompositeDestinationIn = 7, NSCompositeDestinationOut = 8, NSCompositeDestinationAtop = 9, NSCompositeXOR = 10, NSCompositePlusDarker = 11, NSCompositeHighlight = 12, NSCompositePlusLighter = 13 } typedef NSUInteger NSCompositingOperation;
NSCompositeClear
Transparent. (R = 0
)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositeCopy
Source image. (R = S
)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositeSourceOver
Source image wherever source image is opaque, and destination image elsewhere. (R = S + D*(1 - Sa)
)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositeSourceIn
Source image wherever both images are opaque, and transparent elsewhere. (R = S*Da
)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositeSourceOut
Source image wherever source image is opaque but destination image is transparent, and transparent elsewhere. (R = S*(1 - Da)
)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositeSourceAtop
Source image wherever both images are opaque, destination image wherever destination image is opaque but source image is transparent, and transparent elsewhere. (R = S*Da + D*(1 - Sa)
)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositeDestinationOver
Destination image wherever destination image is opaque, and source image elsewhere. (R = S*(1 - Da) + D
)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositeDestinationIn
Destination image wherever both images are opaque, and transparent elsewhere. (R = D*Sa
)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositeDestinationOut
Destination image wherever destination image is opaque but source image is transparent, and transparent elsewhere. (R = D*(1 - Sa)
)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositeDestinationAtop
Destination image wherever both images are opaque, source image wherever source image is opaque but destination image is transparent, and transparent elsewhere. (R = S*(1 - Da) + D*Sa
)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositeXOR
Exclusive OR of source and destination images. (R = S*(1 - Da) + D*(1 - Sa)
)
Works only with black and white images and is not recommended for color contexts.
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositePlusDarker
Sum of source and destination images, with color values approaching 0 as a limit. (R = MAX(0, (1 - D) + (1 - S))
)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositeHighlight
Source image wherever source image is opaque, and destination image elsewhere. (Deprecated. Mapped to NSCompositeSourceOver
.)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
NSCompositePlusLighter
Sum of source and destination images, with color values approaching 1 as a limit. (R = MIN(1, S + D)
)
Available in Mac OS X v10.0 and later.
Declared in NSGraphics.h
.
These compositing operators are defined in and used by compositeToPoint:fromRect:operation:
, compositeToPoint:operation:
, compositeToPoint:fromRect:operation:fraction:
, compositeToPoint:operation:fraction:
, drawAtPoint:fromRect:operation:fraction:
, and drawInRect:fromRect:operation:fraction:
. They are also used by drawing methods in other classes that take a compositing operator.
The equations after each constant represent the mathematical formulas used to calculate the color value of the resulting pixel. Table 2 lists the meaning of each placeholder value in the equations.
Para | Para |
---|---|
| The premultiplied result color. |
| The source color |
| The destination color |
| The alpha value of the source color |
| The alpha value of the destination color |
NSGraphics.h
These constants are status values passed to the incremental loading delegate method image:didLoadRepresentation:withStatus:
.
enum { NSImageLoadStatusCompleted, NSImageLoadStatusCancelled, NSImageLoadStatusInvalidData, NSImageLoadStatusUnexpectedEOF, NSImageLoadStatusReadError } typedef NSUInteger NSImageLoadStatus;
NSImageLoadStatusCompleted
Enough data has been provided to completely decompress the image.
Available in Mac OS X v10.2 and later.
Declared in NSImage.h
.
NSImageLoadStatusCancelled
Image loading was canceled.
The image contains the portions of the data that have already been successfully decompressed, if any.
Available in Mac OS X v10.2 and later.
Declared in NSImage.h
.
NSImageLoadStatusInvalidData
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.
Available in Mac OS X v10.2 and later.
Declared in NSImage.h
.
NSImageLoadStatusUnexpectedEOF
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.
Available in Mac OS X v10.2 and later.
Declared in NSImage.h
.
NSImageLoadStatusReadError
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.
Available in Mac OS X v10.2 and later.
Declared in NSImage.h
.
NSImage.h
These constants specify the caching policy on a per NSImage
basis. The caching policy is set using cacheMode
and setCacheMode:
.
enum { NSImageCacheDefault, NSImageCacheAlways, NSImageCacheBySize, NSImageCacheNever } typedef NSUInteger NSImageCacheMode;
NSImageCacheDefault
Caching is unspecified.
Use the image rep's default.
Available in Mac OS X v10.2 and later.
Declared in NSImage.h
.
NSImageCacheAlways
Always generate a cache when drawing.
Available in Mac OS X v10.2 and later.
Declared in NSImage.h
.
NSImageCacheBySize
Cache if cache size is smaller than the original data.
Available in Mac OS X v10.2 and later.
Declared in NSImage.h
.
NSImageCacheNever
Never cache; always draw direct.
Available in Mac OS X v10.2 and later.
Declared in NSImage.h
.
The following table specifies the default caching policy for the various types of image representation.
Image Rep Class | Default caching policy |
---|---|
|
|
|
|
| |
|
|
| |
|
NSImage.h
Images representing standard artwork and icons that you can use in your applications
NSString *const NSImageNameQuickLookTemplate; NSString *const NSImageNameBluetoothTemplate; NSString *const NSImageNameIChatTheaterTemplate; NSString *const NSImageNameSlideshowTemplate; NSString *const NSImageNameActionTemplate; NSString *const NSImageNameSmartBadgeTemplate; NSString *const NSImageNamePathTemplate; NSString *const NSImageNameInvalidDataFreestandingTemplate; NSString *const NSImageNameLockLockedTemplate; NSString *const NSImageNameLockUnlockedTemplate; NSString *const NSImageNameGoRightTemplate; NSString *const NSImageNameGoLeftTemplate; NSString *const NSImageNameRightFacingTriangleTemplate; NSString *const NSImageNameLeftFacingTriangleTemplate; NSString *const NSImageNameAddTemplate; NSString *const NSImageNameRemoveTemplate; NSString *const NSImageNameRevealFreestandingTemplate; NSString *const NSImageNameFollowLinkFreestandingTemplate; NSString *const NSImageNameEnterFullScreenTemplate; NSString *const NSImageNameExitFullScreenTemplate; NSString *const NSImageNameStopProgressTemplate; NSString *const NSImageNameStopProgressFreestandingTemplate; NSString *const NSImageNameRefreshTemplate; NSString *const NSImageNameRefreshFreestandingTemplate; NSString *const NSImageNameFolder; NSString *const NSImageNameTrashEmpty; NSString *const NSImageNameTrashFull; NSString *const NSImageNameHomeTemplate; NSString *const NSImageNameBookmarksTemplate; NSString *const NSImageNameCaution; NSString *const NSImageNameStatusAvailable; NSString *const NSImageNameStatusPartiallyAvailable; NSString *const NSImageNameStatusUnavailable; NSString *const NSImageNameStatusNone; NSString *const NSImageNameApplicationIcon; NSString *const NSImageNameMenuOnStateTemplate; NSString *const NSImageNameMenuMixedStateTemplate; NSString *const NSImageNameUserGuest; NSString *const NSImageNameMobileMe;
NSImageNameQuickLookTemplate
A Quick Look template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameBluetoothTemplate
A Bluetooth template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameIChatTheaterTemplate
An iChat Theater template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameSlideshowTemplate
A slideshow template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameActionTemplate
An action menu template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameSmartBadgeTemplate
A badge for a “smart” item.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNamePathTemplate
A path button template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameInvalidDataFreestandingTemplate
An invalid data template image. Place this icon to the right of any fields containing invalid data. You can use this image to implement a borderless button.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameLockLockedTemplate
A locked lock template image. Use to indicate locked content.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameLockUnlockedTemplate
An unlocked lock template image. Use to indicate modifiable content that can be locked.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameGoRightTemplate
A “go forward” template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameGoLeftTemplate
A “go back” template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameRightFacingTriangleTemplate
A generic right-facing triangle template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameLeftFacingTriangleTemplate
A generic left-facing triangle template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameAddTemplate
An add item template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameRemoveTemplate
A remove item template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameRevealFreestandingTemplate
A reveal contents template image. You can use this image to implement a borderless button.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameFollowLinkFreestandingTemplate
A link template image. You can use this image to implement a borderless button.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameEnterFullScreenTemplate
An enter full-screen mode template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameExitFullScreenTemplate
An exit full-screen mode template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameStopProgressTemplate
A stop progress button template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameStopProgressFreestandingTemplate
A stop progress template image. You can use this image to implement a borderless button.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameRefreshTemplate
A refresh template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameRefreshFreestandingTemplate
A refresh template image. You can use this image to implement a borderless button.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
To access these images, pass the specified constant to the imageNamed:
method.
Images with the word “Template” in their title identify shapes that are not intended as standalone images. You would typically use these icons as the custom image for a button, or you might apply them to a cell in a control. For example, you might use the NSImageNameLockLockedTemplate
image to indicate an item is not modifiable. Template images should use black and clear colors only and it is fine to include varying levels of alpha.
Images with the word “Freestanding” in their title can be used to implement borderless buttons. You do not need to include any extra bezel artwork behind such images.
You should always use named images according to their intended purpose, and not according to how the image appears when loaded. The appearance of images can change between releases. If you use an image for its intended purpose (and not because of it looks), your code should look correct from release to release.
The size and aspect ratio of system images may change from release to release. In some situations, you should explicitly resize images as appropriate for your use. If you use these images in conjunction with an NSButtonCell
object, however, you can use the setImageScaling:
method of the cell to control scaling instead. Similarly, for an NSSegmentedCell
object, you can use the setImageScaling:forSegment:
method to control scaling.
The string value for each constant is equal to the constant name without the “ImageName” portion. You might need this information to locate images by name in Interface Builder. For example, the constant NSImageNameRefreshFreestandingTemplate
would correspond to an image named “NSRefreshFreestandingTemplate” in Interface Builder.
NSImage.h
Drag images you can use in your applications. To access this image, pass the specified constant to the imageNamed:
method.
NSString *const NSImageNameMultipleDocuments;
NSImageNameMultipleDocuments
A drag image for multiple items.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
You can use this icon as the drag image when dragging multiple items. You should not use this image for any other intended purpose, however. The appearance of images can change between releases. If you use an image for its intended purpose (and not because of how it looks), your code should look correct from release to release.
The size and aspect ratio of system images may change from release to release. In some situations, you should explicitly resize images as appropriate for your use. If you use these images in conjunction with an NSButtonCell
object, however, you can use the setImageScaling:
method of the cell to control scaling instead. Similarly, for an NSSegmentedCell
object, you can use the setImageScaling:forSegment:
method to control scaling.
The string value for each constant is equal to the constant name without the “ImageName” portion. You might need this information to locate images by name in Interface Builder. For example, the constant NSImageNameMultipleDocuments
would correspond to an image named “NSMultipleDocuments” in Interface Builder.
Images representing sharing permission icons that you can use in your applications. To access this image, pass the specified constant to the imageNamed:
method.
NSString *const NSImageNameUser; NSString *const NSImageNameUserGroup; NSString *const NSImageNameEveryone;
NSImageNameUser
Permissions for a single user.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameUserGroup
Permissions for a group of users.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameEveryone
Permissions for all users.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
You should use these images to reflect user and group permission or sharing information. The appearance of images can change between releases. If you use an image for its intended purpose (and not because of how it looks), your code should look correct from release to release.
The size and aspect ratio of system images may change from release to release. In some situations, you should explicitly resize images as appropriate for your use. If you use these images in conjunction with an NSButtonCell
object, however, you can use the setImageScaling:
method of the cell to control scaling instead. Similarly, for an NSSegmentedCell
object, you can use the setImageScaling:forSegment:
method to control scaling.
The string value for each constant is equal to the constant name without the “ImageName” portion. You might need this information to locate images by name in Interface Builder. For example, the constant NSImageNameEveryone
would correspond to an image named “NSEveryone” in Interface Builder.
Images representing Finder items. To access this image, pass the specified constant to the imageNamed:
method.
NSString *const NSImageNameBonjour; NSString *const NSImageNameDotMac; NSString *const NSImageNameComputer; NSString *const NSImageNameFolderBurnable; NSString *const NSImageNameFolderSmart; NSString *const NSImageNameNetwork;
NSImageNameBonjour
A Bonjour icon.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameDotMac
A Dot Mac icon.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameComputer
A computer icon.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameFolderBurnable
A burnable folder icon.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameFolderSmart
A smart folder icon.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameNetwork
A network icon.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
You should use these images to reflect specific elements of the Mac OS X environment. For example, you might use the burnable folder icon if your software allows the user to organize content for burning onto an optical disk. The appearance of images can change between releases. If you use an image for its intended purpose (and not because of how it looks), your code should look correct from release to release.
The size and aspect ratio of system images may change from release to release. In some situations, you should explicitly resize images as appropriate for your use. If you use these images in conjunction with an NSButtonCell
object, however, you can use the setImageScaling:
method of the cell to control scaling instead. Similarly, for an NSSegmentedCell
object, you can use the setImageScaling:forSegment:
method to control scaling.
The string value for each constant is equal to the constant name without the “ImageName” portion. You might need this information to locate images by name in Interface Builder. For example, the constant NSImageNameNetwork
would correspond to an image named “NSNetwork” in Interface Builder.
NSImage.h
Images that you can use in application toolbars. To access this image, pass the specified constant to the imageNamed:
method.
NSString *const NSImageNameUserAccounts; NSString *const NSImageNamePreferencesGeneral; NSString *const NSImageNameAdvanced; NSString *const NSImageNameInfo; NSString *const NSImageNameFontPanel; NSString *const NSImageNameColorPanel;
NSImageNameUserAccounts
User account toolbar icon. Use in a preferences window only.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNamePreferencesGeneral
General preferences toolbar icon. Use in a preferences window only.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameAdvanced
Advanced preferences toolbar icon. Use in a preferences window only.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameInfo
An information toolbar icon.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameFontPanel
A font panel toolbar icon.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameColorPanel
A color panel toolbar icon.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameFolder
A folder image.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameTrashEmpty
An image of the empty trash can.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameTrashFull
An image of the full trash can.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameHomeTemplate
Home image suitable for a template.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameBookmarksTemplate
Bookmarks image suitable for a template.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameCaution
Caution Image.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameStatusAvailable
Small green indicator, similar to iChat’s available image.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameStatusPartiallyAvailable
Small yellow indicator, similar to iChat’s idle image.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameStatusUnavailable
Small red indicator, similar to iChat’s unavailable image.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameStatusNone
Small clear indicator.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameApplicationIcon
Generic application icon.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameMenuOnStateTemplate
A check mark. Drawing these outside of menus is discouraged.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameMenuMixedStateTemplate
A horizontal dash. Drawing these outside of menus is discouraged.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameUserGuest
Shaded user figure.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
NSImageNameMobileMe
MobileMe logo. Note that this is preferred to using the NSImageNameDotMac
image, although that image is not expected to be deprecated.
Available in Mac OS X v10.6 and later.
Declared in NSImage.h
.
You should use these images as icons for toolbar items. The appearance of images can change between releases. If you use an image for its intended purpose (and not because of how it looks), your code should look correct from release to release.
The size and aspect ratio of system images may change from release to release. In some situations, you should explicitly resize images as appropriate for your use. If you use these images in conjunction with an NSButtonCell
object, however, you can use the setImageScaling:
method of the cell to control scaling instead. Similarly, for an NSSegmentedCell
object, you can use the setImageScaling:forSegment:
method to control scaling.
Constants that end in the word "Template" name black and clear images that return YES
for isTemplate
. These images can be processed into variants appropriate for different situations. For example, these images can invert in a selected table view row. See setTemplate:
: for more comments. These images are inappropriate for display without further processing, but NSCell
and its subclasses will perform the processing.
Some images also contain the word "Freestanding". This indicates that an image is appropriate for use as a borderless button, it doesn't need any extra bezel artwork behind it. For example, Safari uses NSImageNameStopProgressFreestandingTemplate
as the stop button in a button on its toolbar, while it uses NSImageNameStopProgressFreestandingTemplate
in the downloads window where it appears inline with a progress indicator.
The string value for each constant is equal to the constant name without the “ImageName” portion. You might need this information to locate images by name in Interface Builder. For example, the constant NSImageNameColorPanel
would correspond to an image named “NSColorPanel” in Interface Builder.
NSImage.h
Images used in segmented controls to switch the current view type. To access this image, pass the specified constant to the imageNamed:
method.
NSString *const NSImageNameIconViewTemplate; NSString *const NSImageNameListViewTemplate; NSString *const NSImageNameColumnViewTemplate; NSString *const NSImageNameFlowViewTemplate;
NSImageNameIconViewTemplate
An icon view mode template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameListViewTemplate
A list view mode template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameColumnViewTemplate
A column view mode template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
NSImageNameFlowViewTemplate
A cover flow view mode template image.
Available in Mac OS X v10.5 and later.
Declared in NSImage.h
.
Images with the word “Template” in their title identify shapes that are not intended as standalone images. You would typically use these icons as the custom image for a button, or you might apply them to a cell in a control. For example, you might use the NSImageNameIconViewTemplate
image to indicate an item is not modifiable. Template images should use black and clear colors only and it is fine to include varying levels of alpha.
You should use these images in conjunction with the buttons (usually part of a segmented control) that change the current viewing mode. The appearance of images can change between releases. If you use an image for its intended purpose (and not because of how it looks), your code should look correct from release to release.
The size and aspect ratio of system images may change from release to release. In some situations, you should explicitly resize images as appropriate for your use. If you use these images in conjunction with an NSButtonCell
object, however, you can use the setImageScaling:
method of the cell to control scaling instead. Similarly, for an NSSegmentedCell
object, you can use the setImageScaling:forSegment:
method to control scaling.
The string value for each constant is equal to the constant name without the “ImageName” portion. You might need this information to locate images by name in Interface Builder. For example, the constant NSImageNameFlowViewTemplate
would correspond to an image named “NSFlowViewTemplate” in Interface Builder.
NSImage.h
Last updated: 2010-08-03