NSColor

Inherits From: NSObject

Conforms To: NSCoding, NSCopying NSObject (NSObject)

Declared In: AppKit/NSColor.h

An NSColor represents a color. The color can be a grayscale value and can include alpha (opacity) information. By sending a set message to an NSColor instance, you set the color for the current PostScript drawing context. This causes subsequently drawn graphics to have the color represented by the NSColor instance.

A color is defined in some particular color space. A color space consists of a set of dimensionssuch as red, green, and blue in the case of RGB space. Each point in the space represents a unique color, and the point's location along each dimension is called a component. An individual color is usually specified by the numeric values of its components, which range from 0.0 to 1.0. For instance, a pure red is specified in RGB space by the component values 1.0, 0.0, and 0.0.

Some color spaces include an alpha component, which defines the color's opacity. An alpha value of 1.0 means completely opaque, and 0.0 means completely transparent. The alpha component is ignored when the color is used on a device that doesn't support alpha, such as a printer.

There are three kinds of color space in OpenStep:

. Device-dependent. This means that a given color might not look the same on different displays and printers.

. Device-independent, also known as calibrated. With this sort of color space, a given color should look the same on all devices.

. Named. The named color space has components that aren't numeric values, but simply names in various catalogs of colors. Named colors come with lookup tables that provide the ability to generate the correct color on a given device.

OpenStep includes six different color spaces, referred to by these enumeration constants:

NSDeviceCMYKColorSpace Cyan, magenta, yellow, black, and alpha components

NSDeviceWhiteColorSpace White and alpha components

NSDeviceRGBColorSpace Red, green, blue, and alpha components

Hue, saturation, brightness, and alpha components

NSCalibratedWhiteColorSpace White and alpha components

NSCalibratedRGBColorSpace Red, green, blue, and alpha components

Hue, saturation, brightness, and alpha components

NSNamedColorSpace Catalog name and color name components

(Color spaces whose names start with NSDevice are device-dependent; those with NSCalibrated are device-independent.)

There's usually no need to retrieve the individual components of a color, but when needed, you can either retrieve a set of components (using such methods as getRed:green:blue:alpha:) or an individual component (using such methods as redComponent). However, it's illegal to ask an NSColor for components that aren't defined for its color space. You can identify the color space by sending a colorSpaceName method to the NSColor. If you need to ask an NSColor for components that aren't in its color space (for instance, when you've gotten the color from the color panel), first convert the color to the appropriate color space using the colorUsingColorSpaceName: method. If the color is already in the specified color space, you get the same color back; otherwise you get a conversion that's usually lossy or that's correct only for the current device. You might also get back nil if the specified conversion can't be done.

Subclasses of NSColor need to implement the colorSpaceName and set methods, as well as the methods that return the components for that color space and the methods in the NSCoding protocol. Some other methodssuch as colorWithAlphaComponent:, isEqual:, and colorUsingColorSpaceName:device:may also be implemented if they make sense for the color space. Mutable subclasses (if any) should additionally implement copyWithZone: to provide a true copy.

Creating an NSColor from Component Values

• + (NSColor *)colorWithCalibratedHue:(float)hue Creates and returns a new NSColor whose color space is saturation:(float)saturation NSCalibratedRGBColorSpace, whose opacity value is brightness:(float)brightness alpha, and whose components in HSB space would be alpha:(float)alpha hue, saturation, and brightness. All values are legal, but values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
• + (NSColor *)colorWithCalibratedRed:(float)red Creates and returns a new NSColor whose color space is green:(float)green NSCalibratedRGBColorSpace, whose opacity value is blue:(float)blue alpha, and whose RGB components are red, green, and alpha:(float)alpha blue. All values are legal, but values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
• + (NSColor *)colorWithCalibratedWhite:(float)white alpha:(float)alpha Creates and returns a new NSColor whose color space is NSCalibratedWhiteColorSpace, whose opacity value is alpha, and whose grayscale value is white. All values are legal, but values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
• + (NSColor *)colorWithCatalogName:(NSString *)listName colorName:(NSString *)colorName Creates and returns a new NSColor whose color space is NSNamedColorSpace, by finding the color named colorName in the catalog named listName.
• + (NSColor *)colorWithDeviceCyan:(float)cyan Creates and returns a new NSColor whose color space is magenta:(float)magenta NSDeviceCMYKColorSpace, whose opacity value is yellow:(float)yellow alpha, and whose CMYK components are cyan, black:(float)black magenta, yellow, and black. All values are legal, but alpha:(float)alpha values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
• + (NSColor *)colorWithDeviceHue:(float)hue Creates and returns a new NSColor whose color space is saturation:(float)saturation NSDeviceRGBColorSpace, whose opacity value is brightness:(float)brightness alpha, and whose components in HSB space would be alpha:(float)alpha hue, saturation, and brightness. All values are legal, but values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
• + (NSColor *)colorWithDeviceRed:(float)red Creates and returns a new NSColor whose color space is green:(float)green NSDeviceRGBColorSpace, whose opacity value is blue:(float)blue alpha, and whose RGB components are red, green, and alpha:(float)alpha blue. All values are legal, but values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
• + (NSColor *)colorWithDeviceWhite:(float)white Creates and returns a new NSColor whose color space is alpha:(float)alpha NSDeviceWhiteColorSpace, whose opacity value is alpha, and whose grayscale value is white. All values are legal, but values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.

• + (NSColor *)blackColor Returns an NSColor in NSCalibratedWhiteColorSpace whose grayscale value is 0.0 and whose alpha value is 1.0.
• + (NSColor *)blueColor Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 0.0, 0.0, 1.0 and whose alpha value is 1.0.
• + (NSColor *)brownColor Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 0.6, 0.4, 0.2 and whose alpha value is 1.0.
• + (NSColor *)clearColor Returns an NSColor in NSCalibratedWhiteColorSpace whose grayscale and alpha values are both 0.0.
• + (NSColor *)cyanColor Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 0.0, 1.0, 1.0 and whose alpha value is 1.0.
• + (NSColor *)darkGrayColor Returns an NSColor in NSCalibratedWhiteColorSpace whose grayscale value is 1/3 and whose alpha value is 1.0.
• + (NSColor *)grayColor Returns an NSColor in NSCalibratedWhiteColorSpace whose grayscale value is 0.5 and whose alpha value is 1.0.
• + (NSColor *)greenColor Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 0.0, 1.0, 0.0 and whose alpha value is 1.0.
• + (NSColor *)lightGrayColor Returns an NSColor in NSCalibratedWhiteColorSpace whose grayscale value is 2/3 and whose alpha value is 1.0.
• + (NSColor *)magentaColor Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 1.0, 0.0, 1.0 and whose alpha value is 1.0.
• + (NSColor *)orangeColor Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 1.0, 0.5, 0.0 and whose alpha value is 1.0.
• + (NSColor *)purpleColor Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 0.5, 0.0, 0.5 and whose alpha value is 1.0.
• + (NSColor *)redColor Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 1.0, 0.0, 0.0 and whose alpha value is 1.0.
• + (NSColor *)whiteColor Returns an NSColor in NSCalibratedWhiteColorSpace whose grayscale and alpha values are both 1.0.
• + (NSColor *)yellowColor Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 1.0, 1.0, 0.0 and whose alpha value is 1.0.

• + (BOOL)ignoresAlpha Returns YES (the default) if the application hides the color panel's opacity slider and sets imported colors' alpha values to 1.0.
• + (void)setIgnoresAlpha:(BOOL)flag If flag is YES, no opacity slider is displayed in the color panel, and colors dragged in or pasted have their alpha values set to 1.0.

• - (void)getCyan:(float *)cyan Returns the CMYK and alpha values in the respective magenta:(float *)magenta arguments. If NULL is passed in as an argument, the yellow:(float *)yellow method doesn't set that value. It's an error if the black:(float *)black receiver isn't a CMYK color. alpha:(float *)alpha
• - (void)getHue:(float *)hue Returns the HSB and alpha values in the respective saturation:(float *)saturation arguments. If NULL is passed in as an argument, the brightness:(float *)brightness method doesn't set that value. It's an error if the alpha:(float *)alpha receiver isn't a CMYK color.
• - (void)getRed:(float *)red Returns the RGB and alpha values in the respective green:(float *)green arguments. If NULL is passed in as an argument, the blue:(float *)blue method doesn't set that value. It's an error if the alpha:(float *)alpha receiver isn't a CMYK color.
• - (void)getWhite:(float *)white Returns the grayscale and alpha values in the respective alpha:(float *)alpha arguments. If NULL is passed in as an argument, the method doesn't set that value. It's an error if the receiver isn't a CMYK color.

• - (float)alphaComponent Returns the alpha (opacity) component (1.0 by default).
• - (float)blackComponent Returns the black component. It's an error if the receiver isn't a CMYK color.
• - (float)blueComponent Returns the blue component. It's an error if the receiver isn't an RGB color.
• - (float)brightnessComponent Returns the brightness component of the HSB color equivalent to the receiver. It's an error if the receiver isn't an RGB color.
• - (NSString *)catalogNameComponent Returns the name of the catalog containing this color, or nil if the receiver's color space isn't NSNamedColorSpace.
• - (NSString *)colorNameComponent Returns the name of this color, or nil if the receiver's color space isn't NSNamedColorSpace.
• - (float)cyanComponent Returns the cyan component. It's an error if the receiver isn't a CMYK color.
• - (float)greenComponent Returns the green component. It's an error if the receiver isn't an RGB color.
• - (float)hueComponent Returns the hue component of the HSB color equivalent to the receiver. It's an error if the receiver isn't an RGB color.
• - (NSString *)localizedCatalogNameComponent Like catalogNameComponent, but returns a localized string.
• - (NSString *)localizedColorNameComponent Like colorNameComponent, but returns a localized string.
• - (float)magentaComponent Returns the magenta component. It's an error if the receiver isn't a CMYK color.
• - (float)redComponent Returns the red component. It's an error if the receiver isn't an RGB color.
• - (float)saturationComponent Returns the saturation component of the HSB color equivalent to the receiver. It's an error if the receiver isn't an RGB color.
• - (float)whiteComponent Returns the white component. It's an error if the receiver isn't a grayscale color.
• - (float)yellowComponent Returns the yellow component. It's an error if the receiver isn't a CMYK color.

• - (NSString *)colorSpaceName Returns the name of the NSColor's color space.
• - (NSColor *)colorUsingColorSpaceName:(NSString *)colorSpace Returns a newly created NSColor whose color is the same as the receiver's, except that the new NSColor is in the color space named colorSpace. This method calls colorUsingColorSpaceName:device: with the current device, indicating that the color is appropriate for the current device (the current window if drawing, or the current printer if printing).
• - (NSColor *)colorUsingColorSpaceName:(NSString *)colorSpace device:(NSDictionary *)deviceDescription Returns a newly created NSColor whose color is the same as the receiver's, except that the new NSColor is in the color space named colorSpace and is specific to the device described by deviceDescription. Changing the Color
• - (NSColor *)blendedColorWithFraction:(float)fraction ofColor:(NSColor *)aColor Returns a newly created NSColor in NSCalibratedRGBColorSpace whose component values are a weighted sum of the receiver's and aColor's. The method converts aColor and a copy of the receiver to RGB, and then sets each component of the returned color to fraction of aColor's value plus 1 - fraction of the receiver's. If the colors can't be converted to NSCalibratedRGBColorSpace, nil is returned.
• - (NSColor *)colorWithAlphaComponent:(float)alpha Returns a newly created NSColor that has the same color space and component values as the receiver, except that its alpha component is alpha. If the receiver's color space doesn't include an alpha component, the receiver is returned.

• + (NSColor *)colorFromPasteboard:(NSPasteboard *)pasteBoard Returns the NSColor currently on the pasteboard, or nil if the pasteboard doesn't contain color data. The returned color's alpha component is set to 1.0 if ignoresAlpha returns YES.
• - (void)writeToPasteboard:(NSPasteboard *)pasteBoard Writes the receiver's data to the pasteboard, unless the pasteboard doesn't support color data (in which case the method does nothing).

• - (void)drawSwatchInRect:(NSRect)rect Draws the current color in the rectangle rect. Subclasses adorn the rectangle in some manner to indicate the type of color. This method is invoked by color wells, swatches, and other user-interface objects that need to display colors.
• - (void)set Sets the color of subsequent PostScript drawing to the color that the receiver represents. If the application is drawing to the screen rather than printing, this method also sets the current drawing context's alpha value to the value returned by alphaComponent.