Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

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 dimensionsÐsuch 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 methodsÐsuch 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.

Creating an NSColor With Preset Components

+ (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.

Ignoring Alpha Components

+ (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.

Retrieving a Set of Components

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

Retrieving Individual Components

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

Converting to Another Color Space

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

Copying and Pasting

+ (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).

Drawing

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