Mac Developer Library

Developer

AppKit Framework Reference NSImage Class Reference

Options
Deployment Target:

On This Page
Language:

NSImage

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

The NSImage class is a high-level interface for manipulating image data. You use instances of this class to load existing images, create new images, and draw the resulting image data into your views. Although you use this class predominantly for image-related operations, the class itself knows little about the underlying image data. Instead, it works in conjunction with one or more image representation objects (subclasses of NSImageRep) to manage and render the image data. For the most part, these interactions are transparent.

The NSImage class serves many purposes, providing support for the following tasks:

  • Loading images stored on disk or at a specified URL.

  • Drawing images into a view or graphics context.

  • Providing the contents of a CALayer object.

  • Creating new images based on a series of captured drawing commands.

  • Producing versions of the image in a different format.

The NSImage class itself is capable of managing image data in a variety of formats. The specific list of formats is dependent on the version of the operating system but includes many standard formats such as TIFF, JPEG, GIF, PNG, and PDF among others. Each format is managed by a specific type of image representation object, whose job is to manage the actual image data. You can get a list of supported formats using the methods described in Determining the Supported Image Types.

For more information about how to use image objects in your app, see Cocoa Drawing Guide.

Using Images with CALayer Objects

Although you can assign an NSImage object directly to the contents property of a CALayer object, doing so may not always yield the best results. Instead of using your image object, you can use the layerContentsForContentsScale: method to obtain an object that you can use for your layer’s contents. That method creates an image that is suited for use as the contents of a layer and that is supports all of the layer’s gravity modes. By contrast, the NSImage class supports only the kCAGravityResize, kCAGravityResizeAspect, and kCAGravityResizeAspectFill modes.

Before calling the layerContentsForContentsScale: method, use the recommendedLayerContentsScale: method to get the recommended scale factor for the resulting image. Listing 1 shows a typical example that uses the scale factor of a window’s backing store as the desired scale factor. From that scale factor, the code gets the recommended scale factor for the specified image object and creates an object that can be assigned to the layer. You might use this code for images that fit the layer bounds precisely or for which you rely on the contentsGravity property of the layer to position or scale the image.

Listing 1Assigning an image to a layer
  • static void updateLayerWithImageInWindow1(NSImage *image, CALayer *layer, NSWindow *window) {
  • CGFloat desiredScaleFactor = [window backingScaleFactor];
  • CGFloat actualScaleFactor = [image recommendedLayerContentsScale:desiredScaleFactor];
  • id layerContents = [image layerContentsForContentsScale:actualScaleFactor];
  • [layer setContents:layerContents];
  • [layer setContentsScale:actualScaleFactor];
  • }
  • Initializes and returns an image object using the specified file.

    Declaration

    Swift

    init?(byReferencingFile filename: String)

    Objective-C

    - (instancetype)initByReferencingFile:(NSString *)filename

    Parameters

    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.

    Return Value

    An initialized NSImage object or nil if the new object cannot be initialized.

    Discussion

    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 app 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 app should do error checking before attempting to use the image; one way to do so is by accessing the valid property to check whether the image can be drawn.

    This method invokes setDataRetained: with an argument of YEStrue, 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes and returns an image object using the specified URL.

    Declaration

    Swift

    init(byReferencingURL url: NSURL)

    Objective-C

    - (instancetype)initByReferencingURL:(NSURL *)url

    Parameters

    url

    The URL identifying the image.

    Return Value

    An initialized NSImage object or nil if the new object cannot be initialized.

    Discussion

    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 app 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 app should do error checking before attempting to use the image; one way to do so is by accessing the valid property to check whether the image can be drawn.

    This method invokes setDataRetained: with an argument of YEStrue, 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Initializes and returns an image object using the contents of a Core Graphics image.

    Declaration

    Swift

    init(CGImage cgImage: CGImage, size size: NSSize)

    Objective-C

    - (instancetype)initWithCGImage:(CGImageRef)cgImage size:(NSSize)size

    Parameters

    cgImage

    The source CGImage.

    size

    The size of the new image. If size is NSZeroSize, the pixel dimensions of cgImage are assumed as the image’s size.

    Return Value

    An initialized NSImage object or nil if the new object cannot be initialized.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Initializes and returns an image object with the contents of the specified file.

    Declaration

    Swift

    init?(contentsOfFile filename: String)

    Objective-C

    - (instancetype)initWithContentsOfFile:(NSString *)filename

    Parameters

    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.

    Return Value

    An initialized NSImage object or nil if the method cannot create an image representation from the contents of the specified file.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes and returns an image object with the contents of the specified URL.

    Declaration

    Swift

    init?(contentsOfURL aUrl: NSURL)

    Objective-C

    - (instancetype)initWithContentsOfURL:(NSURL *)aUrl

    Parameters

    aUrl

    The URL identifying the image.

    Return Value

    An initialized NSImage object or nil if the method cannot create an image representation from the contents of the specified URL.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes and returns an image object using the provided image data.

    Declaration

    Swift

    init?(data data: NSData)

    Objective-C

    - (instancetype)initWithData:(NSData *)data

    Parameters

    data

    The data object containing the image data. The data can be in any format that OS X supports, including PDF, PICT, EPS, or any number of bitmap data formats.

    Return Value

    An initialized NSImage object or nil if the method cannot create an image representation from the contents of the specified data object.

    Discussion

    Use this method in cases where you already have image data in a supported format and want to obtain an NSImage object that represents that data. This method initializes the object with an image representation that is most appropriate for the type of data you provided.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes and returns an image object using the provided image data and ignoring the EXIF orientation tags.

    Declaration

    Swift

    init?(dataIgnoringOrientation data: NSData)

    Objective-C

    - (instancetype)initWithDataIgnoringOrientation:(NSData *)data

    Parameters

    data

    The data object containing the image data. The data can be in any format that OS X supports, including PDF, PICT, EPS, or any number of bitmap data formats.

    Return Value

    An initialized NSImage object or nil if the method cannot create an image representation from the contents of the specified data object.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Initializes and returns an image object with data from the specified pasteboard.

    Declaration

    Swift

    init?(pasteboard pasteboard: NSPasteboard)

    Objective-C

    - (instancetype)initWithPasteboard:(NSPasteboard *)pasteboard

    Parameters

    pasteboard

    The pasteboard containing the image data. The data on the pasteboard can be in any format that OS X supports, including PDF, PICT, EPS, or any number of bitmap data formats.

    Return Value

    An initialized NSImage object or nil if the method cannot create an image from the contents of the pasteboard.

    Discussion

    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.

    Table 1Default pasteboard types for image representations

    Image representation class

    Default pasteboard type

    Default file extensions

    NSBitmapImageRep

    NSTIFFPboardType

    tiff, gif, jpg, and others

    NSPDFImageRep

    NSPDFPboardType

    pdf

    NSEPSImageRep

    NSPostscriptPboardType

    eps

    NSPICTImageRep

    NSPICTPboardType

    pict

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Creates and returns an image object whose contents are drawn using the specified block.

    Declaration

    Swift

    init(size size: NSSize, flipped drawingHandlerShouldBeCalledWithFlippedContext: Bool, drawingHandler drawingHandler: (NSRect) -> Bool) -> NSImage

    Objective-C

    + (NSImage *)imageWithSize:(NSSize)size flipped:(BOOL)drawingHandlerShouldBeCalledWithFlippedContext drawingHandler:(BOOL (^)(NSRect dstRect))drawingHandler

    Parameters

    size

    The size of the image, measured in points.

    drawingHandlerShouldBeCalledWithFlippedContext

    YEStrue to apply a flip transformation to the graphics context before drawing or NOfalse to draw using the default Cocoa coordinate system orientation.

    drawingHandler

    A block that draws the contents of the image representation. This block is copied and stored by the underlying image representation object for later use. It is not executed until you draw the image. Because the block is executed later, it is executed on the same thread on which you draw the image itself, which can be any thread of your app. Therefore, the block must be safe to call from any thread. The block takes the following parameter:

    dstRect

    The destination rectangle in which to draw. The coordinates of this rectangle are specified in points.

    The block returns a Boolean that indicates whether it drew the image successfully. Return YEStrue from your block if it successfully drew the contents or NOfalse if it did not.

    Return Value

    An initialized NSImage object or nil if the object could not be initialized.

    Discussion

    Use this method to generate an image that is correct at any resolution. This method creates an image object with a single NSCustomImageRep object to manage drawing. The image representation uses the block in the drawingHandler parameter to do the actual drawing.

    When you draw the image for the first time, the underlying image representation executes the drawingHandler block. The image object caches the results according to its usual caching policies; see the cacheMode property. As long as the configuration of the destination graphics context does not change in a significant way, subsequent attempts to draw the image reuse the cached results whenever possible. If the pixel density or color space of the destination graphics context changes, though, the image representation throws away any caches and executes the block again to obtain a new version of the image. For example, if you originally drew the image on a standard resolution display but then draw it on a Retina display, the block is executed again to obtain an image at the new resolution.

    The most typical use for this method is to create an image based on vector-based content. In that case, your drawingHandler block would redraw its existing path objects when asked. If you draw a mixture of vectors and images, you need to do more work to ensure that your images are the appropriate resolution for the destination graphics context.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.8 and later.

  • Initializes and returns an image object with the specified dimensions.

    Declaration

    Swift

    init(size aSize: NSSize)

    Objective-C

    - (instancetype)initWithSize:(NSSize)aSize

    Parameters

    aSize

    The size of the image, measured in points.

    Return Value

    An initialized NSImage object with no rendered content.

    Discussion

    This method does not add any image representations to the image object. It is permissible to initialize the image object by passing a size of (0.0, 0.0); however, you must set the size to a non-zero value before using it or an exception will be raised.

    After using this method to initialize an image object, you are expected to provide the image contents before trying to draw the image. You might lock focus on the image and draw to the image or you might explicitly add an image representation that you created.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    size

  • Initializes the image object with a Carbon-style icon resource.

    Declaration

    Swift

    init(iconRef iconRef: IconRef)

    Objective-C

    - (instancetype)initWithIconRef:(IconRef)iconRef

    Parameters

    iconRef

    A reference to a Carbon icon resource.

    Return Value

    An initialized NSImage object.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the image object associated with the specified name.

    Declaration

    Swift

    init?(named name: String) -> NSImage

    Objective-C

    + (NSImage *)imageNamed:(NSString *)name

    Parameters

    name

    The name associated with the desired image. This can be a name you assigned to the image or the name of an image file in your app bundle.

    Return Value

    The NSImage object associated with the specified name or nil if no such image was found.

    Discussion

    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:

    1. Search for an object whose name was set explicitly using the setName: method and currently resides in the image cache.

    2. Search the app'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.)

    3. Search the Application Kit framework for a shared image with the specified name.

    When looking for files in the app 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 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 app's bundle.

    One particularly useful image you can retrieve is your app's icon. This image is set by Cocoa automatically and accessible using the NSImageNameApplicationIcon constant. Icons for other apps 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 app 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 all strong references to the image are subsequently removed, the object may be quietly removed from the cache. Thus, if you plan to hold onto a returned image object, you must maintain a strong reference to 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 specifying nil for the image name.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Registers the receiver under the specified name.

    Declaration

    Swift

    func setName(_ aString: String?) -> Bool

    Objective-C

    - (BOOL)setName:(NSString *)aString

    Parameters

    aString

    The name to associate with the receiver. Specify nil if you want to remove the image from the image cache.

    Return Value

    YEStrue if the receiver was successfully registered with the given name; otherwise, NOfalse.

    Discussion

    If the receiver is already registered under a different name, this method unregisters the other name. If a different image is already registered under the name specified in aString, this method does nothing and returns NOfalse.

    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 app'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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the name associated with the receiver, if any.

    Declaration

    Swift

    func name() -> String?

    Objective-C

    - (NSString *)name

    Return Value

    The name associated with the receiver, or nil if no name is assigned.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setName:

  • size size Property

    The size of the receiver.

    Declaration

    Swift

    var size: NSSize

    Objective-C

    @property NSSize size

    Discussion

    Defaults to {0.0, 0.0} if no size has been set and the size cannot be determined from any of the receiver's image representations. 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value indicating whether the image is a template image.

    Declaration

    Swift

    func isTemplate() -> Bool

    Objective-C

    - (BOOL)isTemplate

    Return Value

    YEStrue if the image is a template image; otherwise, NOfalse.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets whether the image represents a template image.

    Declaration

    Swift

    func setTemplate(_ isTemplate: Bool)

    Objective-C

    - (void)setTemplate:(BOOL)isTemplate

    Parameters

    isTemplate

    Specify YEStrue if the image is a template image; otherwise, NOfalse.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – isTemplate

  • Tests whether the receiver can create an instance of itself using pasteboard data.

    Declaration

    Swift

    class func canInitWithPasteboard(_ pasteboard: NSPasteboard) -> Bool

    Objective-C

    + (BOOL)canInitWithPasteboard:(NSPasteboard *)pasteboard

    Parameters

    pasteboard

    The pasteboard containing the image data.

    Return Value

    YEStrue if the receiver knows how to handle the data on the pasteboard; otherwise, NOfalse.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    class func imageTypes() -> [AnyObject]

    Objective-C

    + (NSArray *)imageTypes

    Return Value

    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.

    Discussion

    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.

    Do not override this method directly. If your app supports custom image types, create and register an NSImageRep subclass that handles those types.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns an array of UTI strings identifying the image types supported directly by the registered image representation objects.

    Declaration

    Swift

    class func imageUnfilteredTypes() -> [AnyObject]

    Objective-C

    + (NSArray *)imageUnfilteredTypes

    Return Value

    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.

    Discussion

    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.

    Do not override this method directly. If your app supports custom image types, create and register an NSImageRep subclass that handles those types.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    + imageTypes

  • Returns an array of strings identifying the image types supported by the registered NSImageRep objects.

    Declaration

    Swift

    class func imageFileTypes() -> [AnyObject]

    Objective-C

    + (NSArray *)imageFileTypes

    Return Value

    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.

    Discussion

    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.

    Do not override this method. If your app supports custom image types, create and register an NSImageRep subclass that handles those types.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Returns an array of strings identifying the file types supported directly by the registered image representation objects.

    Declaration

    Swift

    class func imageUnfilteredFileTypes() -> [AnyObject]

    Objective-C

    + (NSArray *)imageUnfilteredFileTypes

    Return Value

    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.

    Discussion

    The returned list does not contain pasteboard types that are available only through a user-installed filter service.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Returns an array of strings identifying the pasteboard types supported directly by the registered image representation objects.

    Declaration

    Swift

    class func imagePasteboardTypes() -> [AnyObject]

    Objective-C

    + (NSArray *)imagePasteboardTypes

    Return Value

    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.

    Discussion

    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.

    Do not override this method. Instead, override the imageUnfilteredPasteboardTypes method to notify NSImage of the pasteboard types your class supports.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Returns an array of strings identifying the pasteboard types supported directly by the registered image representation objects.

    Declaration

    Swift

    class func imageUnfilteredPasteboardTypes() -> [AnyObject]

    Objective-C

    + (NSArray *)imageUnfilteredPasteboardTypes

    Return Value

    An array of NSString objects, each of which identifies a single supported pasteboard type.

    Discussion

    The returned list does not contain pasteboard types that are supported only through a user-installed filter service.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Adds the specified image representation object to to the receiver.

    Declaration

    Swift

    func addRepresentation(_ imageRep: NSImageRep)

    Objective-C

    - (void)addRepresentation:(NSImageRep *)imageRep

    Parameters

    imageRep

    The image representation to add.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Adds an array of image representation objects to the receiver.

    Declaration

    Swift

    func addRepresentations(_ imageReps: [AnyObject])

    Objective-C

    - (void)addRepresentations:(NSArray *)imageReps

    Parameters

    imageReps

    An array of NSImageRep objects.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • An array containing all of the receiver's image representations. (read-only)

    Declaration

    Swift

    var representations: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *representations

    Discussion

    This property can contain zero or more NSImageRep objects.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Removes the specified image representation from the receiver and releases it.

    Declaration

    Swift

    func removeRepresentation(_ imageRep: NSImageRep)

    Objective-C

    - (void)removeRepresentation:(NSImageRep *)imageRep

    Parameters

    imageRep

    The image representation object you want to remove.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    representations

  • Returns the best representation of the image for the specified rect using the provided hints.

    Declaration

    Swift

    func bestRepresentationForRect(_ rect: NSRect, context referenceContext: NSGraphicsContext?, hints hints: [NSObject : AnyObject]?) -> NSImageRep?

    Objective-C

    - (NSImageRep *)bestRepresentationForRect:(NSRect)rect context:(NSGraphicsContext *)referenceContext hints:(NSDictionary *)hints

    Parameters

    rect

    The area of the image to return.

    referenceContext

    A graphics context. This value can be nil.

    hints

    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.

    Return Value

    The image representation that most closely matches the specified criteria.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • A Boolean value indicating whether the image prefers to choose image representations using color matching or resolution matching.

    Declaration

    Swift

    var prefersColorMatch: Bool

    Objective-C

    @property BOOL prefersColorMatch

    Discussion

    YEStrue if the receiver should match the color capabilities of the rendering device first; otherwise, NOfalse to indicate that resolution matching is preferred. The default value is YEStrue. 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates whether EPS representations are preferred when no other representations match the resolution of the device.

    Declaration

    Swift

    var usesEPSOnResolutionMismatch: Bool

    Objective-C

    @property BOOL usesEPSOnResolutionMismatch

    Discussion

    YEStrue if EPS image representations are preferred; otherwise, NOfalse. The default value is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates whether image representations whose resolution is an integral multiple of the device resolution are considered a match.

    Declaration

    Swift

    var matchesOnMultipleResolution: Bool

    Objective-C

    @property BOOL matchesOnMultipleResolution

    Discussion

    When this property is set to NOfalse, only image representations whose resolution is exactly the same as the device resolution are considered matches. If the property is set to YEStrue and multiple image representations fit this criteria, the one whose resolution is closest to the device resolution is chosen.

    The default value is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws the image in the specified rectangle.

    Declaration

    Swift

    func drawInRect(_ rect: NSRect)

    Objective-C

    - (void)drawInRect:(NSRect)rect

    Parameters

    rect

    The rectangle in which to draw the image, specified in the current coordinate system.

    Discussion

    This method draws the entire image in the specified rectangle, scaling the image as needed. The method composites the image using the NSCompositeSourceOver operation

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.9 and later.

  • Draws all or part of the image at the specified point in the current coordinate system.

    Declaration

    Swift

    func drawAtPoint(_ point: NSPoint, fromRect srcRect: NSRect, operation op: NSCompositingOperation, fraction delta: CGFloat)

    Objective-C

    - (void)drawAtPoint:(NSPoint)point fromRect:(NSRect)srcRect operation:(NSCompositingOperation)op fraction:(CGFloat)delta

    Parameters

    point

    The location in the current coordinate system at which to draw the image.

    srcRect

    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.

    op

    The compositing operation to use when drawing the image. See the NSCompositingOperation constants.

    delta

    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.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws all or part of the image in the specified rectangle in the current coordinate system.

    Declaration

    Swift

    func drawInRect(_ dstRect: NSRect, fromRect srcRect: NSRect, operation op: NSCompositingOperation, fraction delta: CGFloat)

    Objective-C

    - (void)drawInRect:(NSRect)dstRect fromRect:(NSRect)srcRect operation:(NSCompositingOperation)op fraction:(CGFloat)delta

    Parameters

    dstRect

    The rectangle in which to draw the image, specified in the current coordinate system.

    srcRect

    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.

    op

    The compositing operation to use when drawing the image. See the NSCompositingOperation constants.

    delta

    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.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws all or part of the image in the specified rectangle respecting the flippedness and hints.

    Declaration

    Swift

    func drawInRect(_ dstSpacePortionRect: NSRect, fromRect srcSpacePortionRect: NSRect, operation op: NSCompositingOperation, fraction requestedAlpha: CGFloat, respectFlipped respectContextIsFlipped: Bool, hints hints: [NSObject : AnyObject]?)

    Objective-C

    - (void)drawInRect:(NSRect)dstSpacePortionRect fromRect:(NSRect)srcSpacePortionRect operation:(NSCompositingOperation)op fraction:(CGFloat)requestedAlpha respectFlipped:(BOOL)respectContextIsFlipped hints:(NSDictionary *)hints

    Parameters

    dstSpacePortionRect

    The rectangle in which to draw the image, specified in the current coordinate system.

    srcSpacePortionRect

    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.

    op

    The compositing operation to use when drawing the image. See the NSCompositingOperation constants.

    requestedAlpha

    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.

    respectContextIsFlipped

    YEStrue if the drawing should respect the context flipped state, otherwise NOfalse.

    hints

    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.

    Discussion

    If the srcSpacePortionRect and dstSpacePortionRect rectangles have different sizes, the source portion of the image is scaled to fit the specified destination rectangle.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Draws the image using the specified image representation object.

    Declaration

    Swift

    func drawRepresentation(_ imageRep: NSImageRep, inRect dstRect: NSRect) -> Bool

    Objective-C

    - (BOOL)drawRepresentation:(NSImageRep *)imageRep inRect:(NSRect)dstRect

    Parameters

    imageRep

    The image representation object to be drawn.

    dstRect

    The rectangle in which to draw the image representation, specified in the current coordinate system.

    Return Value

    YEStrue if the image was successfully drawn; otherwise, returns NOfalse.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    backgroundColor

  • valid valid Property

    A Boolean value that indicates whether an image representation from the receiver can be drawn. (read-only)

    Declaration

    Swift

    var valid: Bool { get }

    Objective-C

    @property(getter=isValid, readonly) BOOL valid

    Discussion

    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 NOfalse in cases where the file or URL from which it was initialized is nonexistent or when the data in an existing file is invalid.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • The background color for the image.

    Declaration

    Swift

    @NSCopying var backgroundColor: NSColor

    Objective-C

    @property(copy) NSColor *backgroundColor

    Discussion

    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. Assigning a new background color does not cause the receiver to recache itself.

    The default color is transparent, as returned by the clearColor method of NSColor.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – recache

  • Prepares the image to receive drawing commands.

    Declaration

    Swift

    func lockFocus()

    Objective-C

    - (void)lockFocus

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Prepares the image to receive drawing commands using the specified flipped state.

    Declaration

    Swift

    func lockFocusFlipped(_ flipped: Bool)

    Objective-C

    - (void)lockFocusFlipped:(BOOL)flipped

    Parameters

    flipped

    YEStrue if the drawing context should be flipped, otherwise NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Removes the focus from the receiver.

    Declaration

    Swift

    func unlockFocus()

    Objective-C

    - (void)unlockFocus

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A rectangle that your code can use to position the image during layout.

    Declaration

    Swift

    var alignmentRect: NSRect

    Objective-C

    @property NSRect alignmentRect

    Discussion

    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. The NSImage class does not use this rectangle during drawing; however, instances of NSCell typically use this information when laying out images within their boundaries.

    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. This property defaults to a rectangle with an origin of {0, 0} and a size that matches the size of the image.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • cacheMode cacheMode Property

    The image’s caching mode.

    Declaration

    Swift

    var cacheMode: NSImageCacheMode

    Objective-C

    @property NSImageCacheMode cacheMode

    Discussion

    The caching mode determines when the 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 a list of possible values, see NSImageCacheMode. This value is set to NSImageCacheDefault by default.

    For more information on image caching behavior, see the Images chapter of Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Invalidates and frees the offscreen caches of all image representations.

    Declaration

    Swift

    func recache()

    Objective-C

    - (void)recache

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • delegate delegate Property

    The image’s delegate object.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSImageDelegate?

    Objective-C

    @property(assign) id< NSImageDelegate > delegate

    Discussion

    By default, this property contains nil.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A data object containing TIFF data for all of the image representations in the receiver. (read-only)

    Declaration

    Swift

    var TIFFRepresentation: NSData? { get }

    Objective-C

    @property(readonly, strong) NSData *TIFFRepresentation

    Discussion

    Use the value of this property to write the TIFF data to a file. For each image representation, this property 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 property creates the TIFF data from that representation's cached content. This property contains nil if the TIFF data cannot be created.

    Additional image formats can be saved by using the NSBitmapImageRep method representationUsingType:properties:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a data object containing TIFF data with the specified compression settings for all of the image representations in the receiver.

    Declaration

    Swift

    func TIFFRepresentationUsingCompression(_ comp: NSTIFFCompression, factor aFloat: Float) -> NSData?

    Objective-C

    - (NSData *)TIFFRepresentationUsingCompression:(NSTIFFCompression)comp factor:(float)aFloat

    Parameters

    comp

    The type of compression to use. For a list of values, see the constants in NSBitmapImageRep.

    aFloat

    Provides a hint for compression types that implement variable compression ratios. Currently, only JPEG compression uses a compression factor.

    Return Value

    A data object containing the TIFF data, or nil if the TIFF data could not be created.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a CGImage capturing the drawing of the receiver.

    Declaration

    Swift

    func CGImageForProposedRect(_ proposedDestRect: UnsafeMutablePointer<NSRect>, context referenceContext: NSGraphicsContext?, hints hints: [NSObject : AnyObject]?) -> Unmanaged<CGImage>?

    Objective-C

    - (CGImageRef)CGImageForProposedRect:(NSRect *)proposedDestRect context:(NSGraphicsContext *)referenceContext hints:(NSDictionary *)hints

    Parameters

    proposedDestRect

    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.

    referenceContext

    A graphics context.

    hints

    A dictionary of hints that provide more context for selecting or generating a CGImage, and may override properties of the referenceContext.

    Return Value

    A CGImageRef. This may be an existing CGImage if one is available. If not, a new CGImage is created.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Cancels the current download operation immediately, if the image is being incrementally loaded.

    Declaration

    Swift

    func cancelIncrementalLoad()

    Objective-C

    - (void)cancelIncrementalLoad

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Returns whether the destination rectangle would intersect a non-transparent portion of the image.

    Declaration

    Swift

    func hitTestRect(_ testRectDestSpace: NSRect, withImageDestinationRect imageRectDestSpace: NSRect, context referenceContext: NSGraphicsContext?, hints hints: [NSObject : AnyObject]?, flipped flipped: Bool) -> Bool

    Objective-C

    - (BOOL)hitTestRect:(NSRect)testRectDestSpace withImageDestinationRect:(NSRect)imageRectDestSpace context:(NSGraphicsContext *)referenceContext hints:(NSDictionary *)hints flipped:(BOOL)flipped

    Parameters

    testRectDestSpace

    The rectangle to hit test.

    imageRectDestSpace

    A rectangle representing the drawn size of the image.

    referenceContext

    A graphics context. This value can be nil.

    hints

    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.

    flipped

    YEStrue if the image is flipped, otherwise NOfalse.

    Return Value

    YES if the testRectDestSpace intersects with non-transparent content within the imageRectDestSpace, otherwise NO.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • The image’s accessibility description.

    Declaration

    Swift

    var accessibilityDescription: String?

    Objective-C

    @property(copy) NSString *accessibilityDescription

    Discussion

    This description is used automatically by interface elements that display images. Like all accessibility descriptions, use a short localized string that does not include the name of the interface element. For instance, "delete" rather than "delete button".

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns an object that may be used as the contents of a layer.

    Declaration

    Swift

    func layerContentsForContentsScale(_ layerContentsScale: CGFloat) -> AnyObject

    Objective-C

    - (id)layerContentsForContentsScale:(CGFloat)layerContentsScale

    Parameters

    layerContentsScale

    The scale factor for the resulting image. Obtain the value for this parameter by calling the recommendedLayerContentsScale: method.

    Return Value

    A object that you can assign to the contents property of a CALayer object. This object contains the image data from the current image optimized for the specified scale factor.

    Discussion

    Use this method in situations where you want to use the image as the contents of a layer. This method provides the image data wrapped in an object that correctly respects all of the possible content gravities supported by the layer. Use of the returned object as the layer’s contents is recommended over the use of the NSImage object itself.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the recommended layer contents scale for this image.

    Declaration

    Swift

    func recommendedLayerContentsScale(_ preferredContentsScale: CGFloat) -> CGFloat

    Objective-C

    - (CGFloat)recommendedLayerContentsScale:(CGFloat)preferredContentsScale

    Parameters

    preferredContentsScale

    The preferred layer contents scale. Don't use a higher scale factor if the image can't provide it. If the image is resolution independent the return value will be the same as the input. If you specify 0.0 for this parameter, the method uses the scale factor for the default screen.

    Return Value

    The recommended layer contents scale. This scale factor may be different than the one in the preferredContentsScale parameter.

    Discussion

    Use this method to obtain the scale factor value that you pass to the layerContentsForContentsScale: method. This method uses the image data to determine the scale factor that is best suited for creating an image that looks good in the layer.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • A Boolean value that indicates whether the image matches only on the best fitting axis.

    Declaration

    Swift

    var matchesOnlyOnBestFittingAxis: Bool

    Objective-C

    @property BOOL matchesOnlyOnBestFittingAxis

    Discussion

    YEStrue if the image is drawn only on the best fitting axis; otherwise, NOfalse. This property defaults to NOfalse.

    NSImage has always tried to use a representation with at least as many pixels as the destination rectangle. Many apps try to implement banners and 3 part / 9 part images by stretching an NSImage over a much larger area (usually only on a single axis).

    With the addition of 2x assets these apps are finding this policy displays the 2x image rep when they would prefer the 1x rep. This behavior can be changed by using this method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Prepares the specified image representation to receive drawing commands.

    Deprecation Statement

    Use the code fragment shown in the special considerations below.

    Declaration

    Objective-C

    - (void)lockFocusOnRepresentation:(NSImageRep *)imageRepresentation

    Parameters

    imageRepresentation

    An image representation belonging to the receiver, or nil if you want the receiver to choose which image representation to use.

    Discussion

    This method sets the current drawing context to the area of the offscreen window used to cache the specified image representation'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.

    If imageRepresentation is nil, this method acts like the lockFocus method, setting the focus to the best representation for the NSImage object.

    A successful lockFocusOnRepresentation: message must be balanced with a matching unlockFocus message to the same NSImage object. These messages bracket the code that draws the image.

    If lockFocusOnRepresentation: is unable to focus on the specified image representation, it raises an NSImageCacheException.

    Special Considerations

    This method is deprecated as it did not set up imageRepresentation as a drawing destination, it set the image up as a drawing destination, then drew imageRepresentation into it. You can replace this functionality with the following code fragment

    • [image lockFocus];
    • [imageRepresentation drawInRect:NSMakeRect(0,0,[image size].width, [image size].height)];
    • [image unlockFocus];

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    valid

  • Returns the best representation for the device with the specified characteristics.

    Deprecation Statement

    Use bestRepresentationForRect:context:hints: instead.

    Declaration

    Objective-C

    - (NSImageRep *)bestRepresentationForDevice:(NSDictionary *)deviceDescription

    Parameters

    deviceDescription

    A dictionary of attributes for the specified device, or nil to specify the current device. For a list of dictionary keys and values appropriate to display and print devices, see the constants in NSScreen.

    Return Value

    The image representation that most closely matches the specified criteria.

    Discussion

    If deviceDescription is nil, this method uses the attributes of the device on which the content is to be drawn.

    For information on how the "best" representation is chosen, see the Images chapter of Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Composites the entire image to the specified point in the current coordinate system.

    Deprecation Statement

    Use drawAtPoint:fromRect:operation:fraction: instead.

    Declaration

    Objective-C

    - (void)compositeToPoint:(NSPoint)aPoint operation:(NSCompositingOperation)op

    Parameters

    aPoint

    The point at which to draw the image, specified in the current coordinate system.

    op

    The compositing operation to use when drawing the image to the screen. The supported compositing operations are described in Constants.

    Discussion

    This method draws the receiver's best image representation at the specified point in the currently focused view. The entire image is drawn using its current size information. During drawing, the image is composited from its offscreen window cache. Because the offscreen cache is not created until the image representation is first used, this method may need to render the image before compositing. Bitmap representations in particular are not cached until they are explicitly rendered. You can use the lockFocus and unlockFocus methods to force the cached version to be created.

    During printing, this method ignores the op parameter. Even though this parameter is ignored, this method attempts to render the image as close as possible to its appearance when the compositing operation is used on the screen. In either case, the best image representation is chosen for the printing context.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Composites a portion of the image to the specified point in the current coordinate system.

    Deprecation Statement

    Use drawInRect:fromRect:operation:fraction: instead.

    Declaration

    Objective-C

    - (void)compositeToPoint:(NSPoint)aPoint fromRect:(NSRect)srcRect operation:(NSCompositingOperation)op

    Parameters

    aPoint

    The point at which to draw the image, specified in the current coordinate system.

    srcRect

    The portion of the image you want to draw, specified in the image's coordinate system.

    op

    The compositing operation to use when drawing the image to the screen. The supported compositing operations are described in Constants.

    Discussion

    This method draws the specified portion of the image without checking the bounds rectangle you pass into the srcRect parameter. If you specify a source rectangle that strays outside of the image's bounds rectangle, it is conceivable that you could composite parts of the offscreen cache window that do not belong to the receiver's image. You can avoid this problem using the drawAtPoint:fromRect:operation:fraction: method, which checks the source rectangle before drawing.

    During drawing, the image is composited from its offscreen window cache. Because the offscreen cache is not created until the image representation is first used, this method may need to render the image before compositing. Bitmap representations in particular are not cached until they are explicitly rendered. You can use the lockFocus and unlockFocus methods to force the cached version to be created.

    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.

    During printing, this method ignores the op parameter. Even though this parameter is ignored, this method attempts to render the image as close as possible to its appearance when the compositing operation is used on the screen. In either case, the best image representation is chosen for the printing context.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Composites a portion of the image at the specified opacity to the current coordinate system.

    Deprecation Statement

    Use drawInRect:fromRect:operation:fraction: instead.

    Declaration

    Objective-C

    - (void)compositeToPoint:(NSPoint)aPoint fromRect:(NSRect)srcRect operation:(NSCompositingOperation)op fraction:(CGFloat)delta

    Parameters

    aPoint

    The point at which to draw the image, specified in the current coordinate system.

    srcRect

    The portion of the image you want to draw, specified in the image's coordinate system.

    op

    The compositing operation to use when drawing the image to the screen. The supported compositing operations are described in Constants.

    delta

    The desired opacity of the image, specified as a value between 0.0 and 1.0, with 1.0 representing total opacity. Values larger than 1.0 are interpreted as 1.0. This method always expects to render something, so for values that are equal to or less than 0, this method renders at full opacity.

    Discussion

    Behaves the same as compositeToPoint:fromRect:operation: except that you can specify the amount of opacity to use when drawing the image.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Composites the entire image at the specified opacity in the current coordinate system.

    Deprecation Statement

    Use drawAtPoint:fromRect:operation:fraction: instead.

    Declaration

    Objective-C

    - (void)compositeToPoint:(NSPoint)aPoint operation:(NSCompositingOperation)op fraction:(CGFloat)delta

    Parameters

    aPoint

    The point at which to draw the image, specified in the current coordinate system.

    op

    The compositing operation to use when drawing the image to the screen. The supported compositing operations are described in Constants.

    delta

    The desired opacity of the image, specified as a value between 0.0 and 1.0, with 1.0 representing total opacity. Values larger than 1.0 are interpreted as 1.0. This method always expects to render something, so for values that are equal to or less than 0, this method renders at full opacity.

    Discussion

    Behaves the same as compositeToPoint:operation: except that you can specify the amount of opacity to use when drawing the image.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Composites the entire image to the specified location using the NSCompositeSourceOver operator.

    Deprecation Statement

    Use drawAtPoint:fromRect:operation:fraction: instead.

    Declaration

    Objective-C

    - (void)dissolveToPoint:(NSPoint)aPoint fraction:(CGFloat)delta

    Parameters

    aPoint

    The point at which to draw the image, specified in the current coordinate system.

    delta

    The desired opacity of the image, specified as a value between 0.0 and 1.0. A value of 0.0 renders the image totally transparent while 1.0 renders it fully opaque. Values larger than 1.0 are interpreted as 1.0.

    Discussion

    Except for the choice of compositing operator, this method behaves in the same way as the compositeToPoint:operation: method. During printing, the delta parameter is ignored.

    If the source image contains alpha information, this operation may promote the destination NSWindow object to contain alpha information.

    To slowly dissolve this image onto another, you can invoke this method (or the dissolveToPoint:fromRect:fraction: method) repeatedly with an ever-increasing delta value. Because the delta parameter refers to the visible fraction of the source image, increasing the value causes the source image to replace the destination content gradually. You should generally perform this type of operation using a buffered window or other offscreen drawing environment.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Composites a portion of the image to the specified location using the NSCompositeSourceOver operator.

    Deprecation Statement

    Use drawInRect:fromRect:operation:fraction: instead.

    Declaration

    Objective-C

    - (void)dissolveToPoint:(NSPoint)aPoint fromRect:(NSRect)srcRect fraction:(CGFloat)delta

    Parameters

    aPoint

    The point at which to draw the image, specified in the current coordinate system.

    srcRect

    The portion of the image you want to draw, specified in the image's coordinate system.

    delta

    The desired opacity of the image, specified as a value between 0.0 and 1.0. A value of 0.0 renders the image totally transparent while 1.0 renders it fully opaque. Values larger than 1.0 are interpreted as 1.0.

    Discussion

    Except for the choice of compositing operator, this method behaves in the same way as the compositeToPoint:fromRect:operation: method. During printing, the delta parameter is ignored.

    If the source image contains alpha information, this operation may promote the destination NSWindow object to contain alpha information.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Sets whether different-sized image representations are scaled to fit the receiver's size.

    Deprecation Statement

    This method was related to caching behavior. In Mac OS X v10.6 and later, image caching is no longer necessary and as a result there is no replacement necessary.

    Declaration

    Objective-C

    - (void)setScalesWhenResized:(BOOL)flag

    Parameters

    flag

    YEStrue if image representations are scaled to fit; otherwise NOfalse.

    Discussion

    Most images (especially those loaded from files and URLs) contain only a single image representation whose size is the same as the receiver. It is possible to add image representations using the addRepresentation: or addRepresentations: methods but doing so is rarely necessary because modern hardware is powerful enough to resize and scale images quickly. The only reason to consider creating new representations is if each representations contains a customized version of the image at a specific size. (TIFF images may also contain a thumbnail version of an image, which is stored using a separate image representation.) If you pass YEStrue in the flag parameter, and subsequently assign a new value to the size property, all such image representations would be scaled to the same size. Scaling of bitmap images usually results in the interpolation of the bitmap data.

    This method does not invalidate the caches of any of the receiver's image representations. The caches are not invalidated until you change the image size using the size property. Scaling affects only the cached offscreen data for a given image representation.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Returns a Boolean value indicating whether image representations are scaled to fit the receiver's size.

    Deprecation Statement

    This method was related to caching behavior. In Mac OS X v10.6 and later, image caching is no longer necessary and as a result there is no replacement necessary.

    Declaration

    Objective-C

    - (BOOL)scalesWhenResized

    Return Value

    YEStrue if image representations are scaled to fit the receiver; otherwise, NOfalse. The default value is NOfalse.

    Discussion

    Images are not resized during drawing if this method returns YEStrue. They are only resized when you assign a new value to the size property.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Sets whether the receiver retains its source image data.

    Deprecation Statement

    In Mac OS v10.6 and later, NSImage no longer discards data in such a way that the original can no longer be reconstructed. There is no replacement method.

    Declaration

    Objective-C

    - (void)setDataRetained:(BOOL)flag

    Parameters

    flag

    YEStrue if you want the source image data to be retained; otherwise NOfalse.

    Discussion

    Retention of the source image data is important if the source of the image data could change, be moved, or be deleted. Data retention is also useful if you plan to resize an image frequently; otherwise, resizing occurs on a cached copy of the image, which can lose image quality during successive scaling operations. With data retention enabled, the image is resized from the original source data.

    If the responsibility for drawing the image is delegated to another object, there is no reason to retain the image data. Similarly, if the source of the image data is not expected to change or you do not plan to resize the image, you do not need to retain the data. In fact, retaining the data leads to increased memory usage, which could have a negative impact on performance.

    If you create your image object using the initByReferencingFile: method, the only data retained is the name of the source file.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Returns a Boolean value indicating whether the receiver retains its source image data.

    Deprecation Statement

    In Mac OS v10.6 and later, NSImage no longer discards data in such a way that the original can no longer be reconstructed. There is no replacement method.

    Declaration

    Objective-C

    - (BOOL)isDataRetained

    Return Value

    YEStrue if the image retains its source data; otherwise, NOfalse. The default value is NOfalse with some exceptions, which are covered in the discussion.

    Discussion

    For image objects initialized using either the initByReferencingFile: or initByReferencingURL: method, this value is YEStrue by default. The reason is that for these methods, data retention simply involves retaining the filename or URL.

    Data retention increases the memory used by the NSImage object and its image representations.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Sets whether each image representation uses a separate offscreen window to cache its contents.

    Deprecation Statement

    NSImage no longer caches to windows. There is no replacement method

    Declaration

    Objective-C

    - (void)setCachedSeparately:(BOOL)flag

    Parameters

    flag

    YEStrue if you want each of the receiver's image representation objects to use a separate offscreen window for caching; otherwise, NOfalse.

    Discussion

    If you specify NOfalse, a representation can be cached together with other images, though in practice it might not be. This method does not invalidate any existing caches.

    If you plan to resize an NSImage object frequently, it is usually more efficient to cache its representations separately. In some situations, you might also want to enable separate caching if you plan to use the compositeToPoint:fromRect:operation: or compositeToPoint:fromRect:operation:fraction:methods to draw the image.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    – recache

  • Returns a Boolean value indicating whether each image representation caches its contents in a separate offscreen window.

    Deprecation Statement

    NSImage no longer caches to windows. There is no replacement method

    Declaration

    Objective-C

    - (BOOL)isCachedSeparately

    Return Value

    YEStrue if the image representations cache their content in separate offscreen windows; otherwise, NOfalse. The default value is NOfalse.

    Discussion

    If this method returns NOfalse, it means that the image may be cached in a shared window but is not required to be. Images are cached in a shared window if they have the same general attributes, such as color space, resolution, and bit depth.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Sets whether the receiver's offscreen window caches use the same bit depth as the image data itself.

    Deprecation Statement

    NSImage no longer caches to windows. A cache is now generated appropriate for the destination where an image is drawn. There is no replacement method.

    Declaration

    Objective-C

    - (void)setCacheDepthMatchesImageDepth:(BOOL)flag

    Parameters

    flag

    YEStrue if the offscreen caches use the same bit-depth associated with the image data; otherwise, NOfalse to indicate they should use the default bit depth.

    Discussion

    This method does not cause the receiver to recache itself. The default depth limit is equal to the bit depth of the deepest screen on the system.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Returns a Boolean value indicating whether an image's offscreen window caches use the same bit depth as the image data itself.

    Deprecation Statement

    NSImage no longer caches to windows. A cache is now generated appropriate for the destination where an image is drawn. There is no replacement method.

    Declaration

    Objective-C

    - (BOOL)cacheDepthMatchesImageDepth

    Return Value

    YEStrue if the offscreen window caches use the same bit depth as the image data; otherwise, NOfalse. The default value is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • setFlipped: - setFlipped: (OS X v10.6)

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

    Deprecation Statement

    The flipped property of an image was widely misunderstood and has been deprecated. Use drawInRect:fromRect:operation:fraction:respectFlipped:hints: to draw respecting a context’s flipped status and lockFocusFlipped: to draw into a flipped image.

    Declaration

    Objective-C

    - (void)setFlipped:(BOOL)flag

    Parameters

    flag

    YEStrue if you want the image data to be inverted before drawing; otherwise, NOfalse.

    Discussion

    If flag is YEStrue, the y-axis of the image's internal coordinate system is inverted, with the origin in the upper-left corner and the positive y axis extending downward. This method affects only the coordinate system used internally by the image and the orientation of the image when it is drawn; it does not affect the coordinate system used to specify the position of an image in a view. This method does not cause the receiver to recache itself.

    If you set flag to YEStrue and then lock focus and draw into the image, the content you draw is cached in the inverted (flipped) orientation. Changing the value for flag does not affect the orientation of the cached image.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • isFlipped - isFlipped (OS X v10.6)

    Returns a Boolean value indicating whether the image uses a flipped coordinate system.

    Deprecation Statement

    The flipped property of an image was widely misunderstood and has been deprecated. Use drawInRect:fromRect:operation:fraction:respectFlipped:hints: to draw respecting a context’s flipped status and lockFocusFlipped: to draw into a flipped image.

    Declaration

    Objective-C

    - (BOOL)isFlipped

    Return Value

    YEStrue if the image's coordinate system is flipped; otherwise, NOfalse. The default is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    – setFlipped:

Data Types

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

    Declaration

    Swift

    enum NSCompositingOperation : UInt { case CompositeClear case CompositeCopy case CompositeSourceOver case CompositeSourceIn case CompositeSourceOut case CompositeSourceAtop case CompositeDestinationOver case CompositeDestinationIn case CompositeDestinationOut case CompositeDestinationAtop case CompositeXOR case CompositePlusDarker case CompositeHighlight case CompositePlusLighter case CompositeMultiply case CompositeScreen case CompositeOverlay case CompositeDarken case CompositeLighten case CompositeColorDodge case CompositeColorBurn case CompositeSoftLight case CompositeHardLight case CompositeDifference case CompositeExclusion case CompositeHue case CompositeSaturation case CompositeColor case CompositeLuminosity }

    Objective-C

    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;

    Constants

    • CompositeClear

      NSCompositeClear

      Transparent. (R = 0)

      Available in OS X v10.0 and later.

    • CompositeCopy

      NSCompositeCopy

      Source image. (R = S)

      Available in OS X v10.0 and later.

    • CompositeSourceOver

      NSCompositeSourceOver

      Source image wherever source image is opaque, and destination image elsewhere. (R = S + D*(1 - Sa))

      Available in OS X v10.0 and later.

    • CompositeSourceIn

      NSCompositeSourceIn

      Source image wherever both images are opaque, and transparent elsewhere. (R = S*Da)

      Available in OS X v10.0 and later.

    • CompositeSourceOut

      NSCompositeSourceOut

      Source image wherever source image is opaque but destination image is transparent, and transparent elsewhere. (R = S*(1 - Da))

      Available in OS X v10.0 and later.

    • CompositeSourceAtop

      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 OS X v10.0 and later.

    • CompositeDestinationOver

      NSCompositeDestinationOver

      Destination image wherever destination image is opaque, and source image elsewhere. (R = S*(1 - Da) + D)

      Available in OS X v10.0 and later.

    • CompositeDestinationIn

      NSCompositeDestinationIn

      Destination image wherever both images are opaque, and transparent elsewhere. (R = D*Sa)

      Available in OS X v10.0 and later.

    • CompositeDestinationOut

      NSCompositeDestinationOut

      Destination image wherever destination image is opaque but source image is transparent, and transparent elsewhere. (R = D*(1 - Sa))

      Available in OS X v10.0 and later.

    • CompositeDestinationAtop

      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 OS X v10.0 and later.

    • CompositeXOR

      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 OS X v10.0 and later.

    • CompositePlusDarker

      NSCompositePlusDarker

      Sum of source and destination images, with color values approaching 0 as a limit. (R = MAX(0, (1 - D) + (1 - S)))

      Available in OS X v10.0 and later.

    • NSCompositeHighlight

      NSCompositeHighlight

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

      Mapped to NSCompositeSourceOver.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.0.

    • CompositePlusLighter

      NSCompositePlusLighter

      Sum of source and destination images, with color values approaching 1 as a limit. (R = MIN(1, S + D))

      Available in OS X v10.0 and later.

    Discussion

    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.

    Table 2Placeholder values for compositing equations

    Para

    Para

    R

    The premultiplied result color.

    S

    The source color

    D

    The destination color

    Sa

    The alpha value of the source color

    Da

    The alpha value of the destination color

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • These constants are status values passed to the incremental loading delegate method image:didLoadRepresentation:withStatus:.

    Declaration

    Swift

    enum NSImageLoadStatus : UInt { case Completed case Cancelled case InvalidData case UnexpectedEOF case ReadError }

    Objective-C

    enum { NSImageLoadStatusCompleted, NSImageLoadStatusCancelled, NSImageLoadStatusInvalidData, NSImageLoadStatusUnexpectedEOF, NSImageLoadStatusReadError } typedef NSUInteger NSImageLoadStatus;

    Constants

    • Completed

      NSImageLoadStatusCompleted

      Enough data has been provided to completely decompress the image.

      Available in OS X v10.2 and later.

    • Cancelled

      NSImageLoadStatusCancelled

      Image loading was canceled.

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

      Available in OS X v10.2 and later.

    • InvalidData

      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 OS X v10.2 and later.

    • UnexpectedEOF

      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 OS X v10.2 and later.

    • ReadError

      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 OS X v10.2 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in Mac OS X v10.2 and later.

  • These constants specify the caching policy on a per NSImage basis. The caching policy is set using the cacheMode property.

    Declaration

    Swift

    enum NSImageCacheMode : UInt { case Default case Always case BySize case Never }

    Objective-C

    enum { NSImageCacheDefault, NSImageCacheAlways, NSImageCacheBySize, NSImageCacheNever } typedef NSUInteger NSImageCacheMode;

    Constants

    • Default

      NSImageCacheDefault

      Caching is unspecified.

      Use the image rep's default.

      Available in OS X v10.2 and later.

    • Always

      NSImageCacheAlways

      Always generate a cache when drawing.

      Available in OS X v10.2 and later.

    • BySize

      NSImageCacheBySize

      Cache if cache size is smaller than the original data.

      Available in OS X v10.2 and later.

    • Never

      NSImageCacheNever

      Never cache; always draw direct.

      Available in OS X v10.2 and later.

    Discussion

    The following table specifies the default caching policy for the various types of image representation.

    Image Rep Class

    Default caching policy

    NSBitmapImageRep

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

    NSPICTImageRep

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

    NSPDFImageRep

    NSImageCacheAlways

    NSCIImageRep

    NSImageCacheBySize. Cache if the bitmap depth does not match the screen depth or the resolution is greater than 72 dpi.

    NSEPSImageRep

    NSImageCacheAlways

    NSCustomImageRep

    NSImageCacheAlways

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in Mac OS X v10.2 and later.

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

    Declaration

    Swift

    let NSImageHintCTM: String let NSImageHintInterpolation: String

    Objective-C

    NSString *const NSImageHintCTM; NSString *const NSImageHintInterpolation;

    Constants

    • NSImageHintCTM

      NSImageHintCTM

      Provides a context transform hint. The value for this key is an NSAffineTransform.

      Available in OS X v10.6 and later.

    • NSImageHintInterpolation

      NSImageHintInterpolation

      Provides an interpolation hint. The value for this key is an NSNumber with an NSImageInterpolation value.

      Available in OS X v10.6 and later.

  • Images representing standard artwork and icons that you can use in your apps

    Declaration

    Swift

    let NSImageNameQuickLookTemplate: String let NSImageNameBluetoothTemplate: String let NSImageNameIChatTheaterTemplate: String let NSImageNameSlideshowTemplate: String let NSImageNameActionTemplate: String let NSImageNameSmartBadgeTemplate: String let NSImageNamePathTemplate: String let NSImageNameInvalidDataFreestandingTemplate: String let NSImageNameLockLockedTemplate: String let NSImageNameLockUnlockedTemplate: String let NSImageNameGoRightTemplate: String let NSImageNameGoLeftTemplate: String let NSImageNameRightFacingTriangleTemplate: String let NSImageNameLeftFacingTriangleTemplate: String let NSImageNameAddTemplate: String let NSImageNameRemoveTemplate: String let NSImageNameRevealFreestandingTemplate: String let NSImageNameFollowLinkFreestandingTemplate: String let NSImageNameEnterFullScreenTemplate: String let NSImageNameExitFullScreenTemplate: String let NSImageNameStopProgressTemplate: String let NSImageNameStopProgressFreestandingTemplate: String let NSImageNameRefreshTemplate: String let NSImageNameRefreshFreestandingTemplate: String

    Objective-C

    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;

    Constants

    • NSImageNameQuickLookTemplate

      NSImageNameQuickLookTemplate

      A Quick Look template image. image: ../Art/NSQuickLookTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameBluetoothTemplate

      NSImageNameBluetoothTemplate

      A Bluetooth template image. image: ../Art/NSBluetoothTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameIChatTheaterTemplate

      NSImageNameIChatTheaterTemplate

      An iChat Theater template image. image: ../Art/NSIchatTheaterTemplate.jpg is missing from your submission.

      Available in OS X v10.5 and later.

    • NSImageNameSlideshowTemplate

      NSImageNameSlideshowTemplate

      A slideshow template image. image: ../Art/NSSlideshowTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameActionTemplate

      NSImageNameActionTemplate

      An action menu template image. image: ../Art/NSActionTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameSmartBadgeTemplate

      NSImageNameSmartBadgeTemplate

      A badge for a “smart” item. image: ../Art/NSSmartBadgeTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNamePathTemplate

      NSImageNamePathTemplate

      A path button template image. image: ../Art/NSPathTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameInvalidDataFreestandingTemplate

      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. image: ../art/NSInvalidDataFreestandingTemplate_2x.png

      Available in OS X v10.5 and later.

    • NSImageNameLockLockedTemplate

      NSImageNameLockLockedTemplate

      A locked lock template image. Use to indicate locked content. image: ../Art/NSLockLockedTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameLockUnlockedTemplate

      NSImageNameLockUnlockedTemplate

      An unlocked lock template image. Use to indicate modifiable content that can be locked. image: ../Art/NSLockUnlockedTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameGoRightTemplate

      NSImageNameGoRightTemplate

      A “go forward” template image. image: ../Art/NSGoRightTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameGoLeftTemplate

      NSImageNameGoLeftTemplate

      A “go back” template image. image: ../Art/NSGoLeftTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameRightFacingTriangleTemplate

      NSImageNameRightFacingTriangleTemplate

      A generic right-facing triangle template image. image: ../Art/NSRightFacingTriangleTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameLeftFacingTriangleTemplate

      NSImageNameLeftFacingTriangleTemplate

      A generic left-facing triangle template image. image: ../Art/NSLeftFacingTriangleTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameAddTemplate

      NSImageNameAddTemplate

      An add item template image. image: ../Art/NSAddTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameRemoveTemplate

      NSImageNameRemoveTemplate

      A remove item template image. image: ../Art/NSRemoveTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameRevealFreestandingTemplate

      NSImageNameRevealFreestandingTemplate

      A reveal contents template image. You can use this image to implement a borderless button. image: ../art/NSRevealFreestandingTemplate_2x.png

      Available in OS X v10.5 and later.

    • NSImageNameFollowLinkFreestandingTemplate

      NSImageNameFollowLinkFreestandingTemplate

      A link template image. You can use this image to implement a borderless button. image: ../art/NSFollowLinkFreestandingTemplate_2x.png

      Available in OS X v10.5 and later.

    • NSImageNameEnterFullScreenTemplate

      NSImageNameEnterFullScreenTemplate

      An enter full-screen mode template image. image: ../Art/NSEnterFullScreenTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameExitFullScreenTemplate

      NSImageNameExitFullScreenTemplate

      An exit full-screen mode template image. image: ../Art/NSExitFullScreenTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameStopProgressTemplate

      NSImageNameStopProgressTemplate

      A stop progress button template image. image: ../Art/NSStopProgressTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameStopProgressFreestandingTemplate

      NSImageNameStopProgressFreestandingTemplate

      A stop progress template image. You can use this image to implement a borderless button. image: ../art/NSStopProgressFreestandingTemplate_2x.png

      Available in OS X v10.5 and later.

    • NSImageNameRefreshTemplate

      NSImageNameRefreshTemplate

      A refresh template image. image: ../Art/NSRefreshTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameRefreshFreestandingTemplate

      NSImageNameRefreshFreestandingTemplate

      A refresh template image. You can use this image to implement a borderless button. image: ../art/NSRefreshFreestandingTemplate_2x.png

      Available in OS X v10.5 and later.

    Discussion

    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.

  • Drag images you can use in your apps. To access this image, pass the specified constant to the imageNamed: method.

    Declaration

    Swift

    let NSImageNameMultipleDocuments: String

    Objective-C

    NSString *const NSImageNameMultipleDocuments;

    Constants

    • NSImageNameMultipleDocuments

      NSImageNameMultipleDocuments

      A drag image for multiple items. image: ../Art/NSMultipleDocuments.jpg

      Available in OS X v10.5 and later.

    Discussion

    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 apps. To access this image, pass the specified constant to the imageNamed: method.

    Declaration

    Swift

    let NSImageNameUser: String let NSImageNameUserGroup: String let NSImageNameEveryone: String let NSImageNameUserGuest: String

    Objective-C

    NSString *const NSImageNameUser; NSString *const NSImageNameUserGroup; NSString *const NSImageNameEveryone; NSString *const NSImageNameUserGuest;

    Constants

    • NSImageNameUser

      NSImageNameUser

      Permissions for a single user. image: ../Art/NSUser.jpg

      Available in OS X v10.5 and later.

    • NSImageNameUserGroup

      NSImageNameUserGroup

      Permissions for a group of users. image: ../Art/NSUserGroup.jpg

      Available in OS X v10.5 and later.

    • NSImageNameEveryone

      NSImageNameEveryone

      Permissions for all users. image: ../Art/NSEveryone.jpg

      Available in OS X v10.5 and later.

    • NSImageNameUserGuest

      NSImageNameUserGuest

      Permissions for guests.image: ../Art/NSUserGuest.png

      Available in OS X v10.6 and later.

    Discussion

    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.

    Declaration

    Swift

    let NSImageNameBonjour: String let NSImageNameComputer: String let NSImageNameFolderBurnable: String let NSImageNameFolderSmart: String let NSImageNameNetwork: String

    Objective-C

    NSString *const NSImageNameBonjour; NSString *const NSImageNameDotMac; NSString *const NSImageNameComputer; NSString *const NSImageNameFolderBurnable; NSString *const NSImageNameFolderSmart; NSString *const NSImageNameNetwork;

    Constants

    • NSImageNameBonjour

      NSImageNameBonjour

      A Bonjour icon. image: ../Art/NSBonjour.jpg

      Available in OS X v10.5 and later.

    • NSImageNameDotMac

      NSImageNameDotMac

      A Dot Mac icon. image: ../Art/NSDotMac.jpg

      Available in OS X v10.5 and later.

      Deprecated in OS X v10.7.

    • NSImageNameComputer

      NSImageNameComputer

      A computer icon. image: ../Art/NSComputer.jpg

      Available in OS X v10.5 and later.

    • NSImageNameFolderBurnable

      NSImageNameFolderBurnable

      A burnable folder icon. image: ../Art/NSFolderBurnable.jpg

      Available in OS X v10.5 and later.

    • NSImageNameFolderSmart

      NSImageNameFolderSmart

      A smart folder icon. image: ../Art/NSFolderSmart.jpg

      Available in OS X v10.5 and later.

    • NSImageNameNetwork

      NSImageNameNetwork

      A network icon. image: ../Art/NSNetwork.jpg

      Available in OS X v10.5 and later.

    Discussion

    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.

  • Images that you can use in app toolbars. To access this image, pass the specified constant to the imageNamed: method.

    Declaration

    Swift

    let NSImageNameUserAccounts: String let NSImageNamePreferencesGeneral: String let NSImageNameAdvanced: String let NSImageNameInfo: String let NSImageNameFontPanel: String let NSImageNameColorPanel: String let NSImageNameFolder: String let NSImageNameTrashEmpty: String let NSImageNameTrashFull: String let NSImageNameHomeTemplate: String let NSImageNameBookmarksTemplate: String let NSImageNameCaution: String let NSImageNameStatusAvailable: String let NSImageNameStatusPartiallyAvailable: String let NSImageNameStatusUnavailable: String let NSImageNameStatusNone: String let NSImageNameApplicationIcon: String let NSImageNameMenuOnStateTemplate: String let NSImageNameMenuMixedStateTemplate: String let NSImageNameMobileMe: String

    Objective-C

    NSString *const NSImageNameUserAccounts; NSString *const NSImageNamePreferencesGeneral; NSString *const NSImageNameAdvanced; NSString *const NSImageNameInfo; NSString *const NSImageNameFontPanel; NSString *const NSImageNameColorPanel; 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 NSImageNameMobileMe;

    Constants

    • NSImageNameUserAccounts

      NSImageNameUserAccounts

      User account toolbar icon. Use in a preferences window only. image: ../Art/NSUserAccounts.jpg

      Available in OS X v10.5 and later.

    • NSImageNamePreferencesGeneral

      NSImageNamePreferencesGeneral

      General preferences toolbar icon. Use in a preferences window only. image: ../Art/NSPreferencesGeneral.jpg

      Available in OS X v10.5 and later.

    • NSImageNameAdvanced

      NSImageNameAdvanced

      Advanced preferences toolbar icon. Use in a preferences window only. image: ../Art/NSAdvanced.jpg

      Available in OS X v10.5 and later.

    • NSImageNameInfo

      NSImageNameInfo

      An information toolbar icon. image: ../Art/NSInfo.jpg

      Available in OS X v10.5 and later.

    • NSImageNameFontPanel

      NSImageNameFontPanel

      A font panel toolbar icon. image: ../Art/NSFontPanel.jpg

      Available in OS X v10.5 and later.

    • NSImageNameColorPanel

      NSImageNameColorPanel

      A color panel toolbar icon. image: ../Art/NSColorPanel.jpg

      Available in OS X v10.5 and later.

    • NSImageNameFolder

      NSImageNameFolder

      A folder image. image: ../Art/NSFolder.png

      Available in OS X v10.6 and later.

    • NSImageNameTrashEmpty

      NSImageNameTrashEmpty

      An image of the empty trash can.image: ../Art/NSTrashEmpty.png

      Available in OS X v10.6 and later.

    • NSImageNameTrashFull

      NSImageNameTrashFull

      An image of the full trash can.image: ../Art/NSTrashFull.png

      Available in OS X v10.6 and later.

    • NSImageNameHomeTemplate

      NSImageNameHomeTemplate

      Home image suitable for a template.image: ../Art/NSHomeTemplate.png

      Available in OS X v10.6 and later.

    • NSImageNameBookmarksTemplate

      NSImageNameBookmarksTemplate

      Bookmarks image suitable for a template.image: ../Art/NSBookmarksTemplate.png

      Available in OS X v10.6 and later.

    • NSImageNameCaution

      NSImageNameCaution

      Caution Image.image: ../Art/NSCaution.png

      Available in OS X v10.6 and later.

    • NSImageNameStatusAvailable

      NSImageNameStatusAvailable

      Small green indicator, similar to iChat’s available image. image: ../Art/NSStatusAvailable.png

      Available in OS X v10.6 and later.

    • NSImageNameStatusPartiallyAvailable

      NSImageNameStatusPartiallyAvailable

      Small yellow indicator, similar to iChat’s idle image.image: ../Art/NSStatusPartiallyAvailable.png

      Available in OS X v10.6 and later.

    • NSImageNameStatusUnavailable

      NSImageNameStatusUnavailable

      Small red indicator, similar to iChat’s unavailable image.image: ../Art/NSStatusUnavailable.png

      Available in OS X v10.6 and later.

    • NSImageNameStatusNone

      NSImageNameStatusNone

      Small clear indicator.image: ../Art/NSStatusNone.png

      Available in OS X v10.6 and later.

    • NSImageNameApplicationIcon

      NSImageNameApplicationIcon

      The app’s icon.

      On versions of Mac OS X prior to v10.6, you can use the string @"NSApplicationIcon".

      Available in OS X v10.6 and later.

    • NSImageNameMenuOnStateTemplate

      NSImageNameMenuOnStateTemplate

      A check mark. Drawing these outside of menus is discouraged.image: ../Art/NSMenuOnStateTemplate.png

      Available in OS X v10.6 and later.

    • NSImageNameMenuMixedStateTemplate

      NSImageNameMenuMixedStateTemplate

      A horizontal dash. Drawing these outside of menus is discouraged. image: ../Art/NSMenuMixedStateTemplate.png

      Available in OS X v10.6 and later.

    • NSImageNameMobileMe

      NSImageNameMobileMe

      MobileMe logo. Note that this is preferred to using the NSImageNameDotMac image, although that image is not expected to be deprecated. image: ../art/NSMobileMe_2x.png

      Available in OS X v10.6 and later.

    Discussion

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

    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.

  • Images used in segmented controls to switch the current view type. To access this image, pass the specified constant to the imageNamed: method.

    Declaration

    Swift

    let NSImageNameIconViewTemplate: String let NSImageNameListViewTemplate: String let NSImageNameColumnViewTemplate: String let NSImageNameFlowViewTemplate: String let NSImageNameShareTemplate: String

    Objective-C

    NSString *const NSImageNameIconViewTemplate; NSString *const NSImageNameListViewTemplate; NSString *const NSImageNameColumnViewTemplate; NSString *const NSImageNameFlowViewTemplate; NSString *const NSImageNameShareTemplate;

    Constants

    • NSImageNameIconViewTemplate

      NSImageNameIconViewTemplate

      An icon view mode template image. image: ../Art/NSIconViewTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameListViewTemplate

      NSImageNameListViewTemplate

      A list view mode template image. image: ../Art/NSListViewTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameColumnViewTemplate

      NSImageNameColumnViewTemplate

      A column view mode template image. image: ../Art/NSColumnViewTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameFlowViewTemplate

      NSImageNameFlowViewTemplate

      A cover flow view mode template image. image: ../Art/NSFlowViewTemplate.jpg

      Available in OS X v10.5 and later.

    • NSImageNameShareTemplate

      NSImageNameShareTemplate

      A share view template image. image: ../art/NSShareTemplate_2x.png

      Available in OS X v10.8 and later.

    Discussion

    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.