---

NSColor Class Reference

Class at a Glance

An NSColor object represents a color, which is defined in a color space, each point of which has a set of components (such as red, green, and blue) that uniquely define a color.

Principal Attributes

• Color space

• Color components

Creation

• Various colorWith... and colorUsing... methods.

• Preset colors: blackColor, blueColor, and so on.

Commonly Used Methods

colorUsingColorSpaceName:

Creates an NSColor instance in the specified color space.

set

Sets the drawing color.

Overview

An NSColor object represents color and sometimes opacity (alpha). By sending a set message to an NSColor instance, you set the color for the current drawing context. Setting the color causes subsequently drawn graphics to have the color represented by the NSColor instance.

It is invalid to use an accessor method related to components of a particular color space on an NSColor object that is not in that color space. For example, methods such as redComponent and getRed:green:blue:alpha: work on color objects in the calibrated and device RGB color spaces. If you send such a message to an NSColor object in the CMYK color space, an exception is raised. If you have an NSColor object in an unknown color space and you want to extract its components, you should first convert the color object to a known color space before using the component accessor methods of that color space.

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

• – copyWithZone:

Tasks

Creating an NSColor Object from Component Values

• + colorWithCalibratedHue:saturation:brightness:alpha:
• + colorWithCalibratedRed:green:blue:alpha:
• + colorWithCalibratedWhite:alpha:
• + colorWithCatalogName:colorName:
• + colorWithDeviceCyan:magenta:yellow:black:alpha:
• + colorWithDeviceHue:saturation:brightness:alpha:
• + colorWithDeviceRed:green:blue:alpha:
• + colorWithDeviceWhite:alpha:
• + colorWithCIColor:
• + colorWithColorSpace:components:count:

Creating an NSColor with Preset Components

• + blackColor
• + blueColor
• + brownColor
• + clearColor
• + cyanColor
• + darkGrayColor
• + grayColor
• + greenColor
• + lightGrayColor
• + magentaColor
• + orangeColor
• + purpleColor
• + redColor
• + whiteColor
• + yellowColor

Working with Pattern Images

• + colorWithPatternImage:
• – patternImage

Creating a System Color—an NSColor Whose Value Is Specified by User Preferences

• + alternateSelectedControlColor
• + alternateSelectedControlTextColor
• + colorForControlTint:
• + controlBackgroundColor
• + controlColor
• + controlAlternatingRowBackgroundColors
• + controlHighlightColor
• + controlLightHighlightColor
• + controlShadowColor
• + controlDarkShadowColor
• + controlTextColor
• + currentControlTint
• + disabledControlTextColor
• + gridColor
• + headerColor
• + headerTextColor
• + highlightColor
• + keyboardFocusIndicatorColor
• + knobColor
• + scrollBarColor
• + secondarySelectedControlColor
• + selectedControlColor
• + selectedControlTextColor
• + selectedMenuItemColor
• + selectedMenuItemTextColor
• + selectedTextBackgroundColor
• + selectedTextColor
• + selectedKnobColor
• + shadowColor
• + textBackgroundColor
• + textColor
• + windowBackgroundColor
• + windowFrameColor
• + windowFrameTextColor

Ignoring Alpha Components

• + ignoresAlpha
• + setIgnoresAlpha:

Copying and Pasting

• + colorFromPasteboard:
• – writeToPasteboard:

Retrieving a Set of Components

• – getCyan:magenta:yellow:black:alpha:
• – getHue:saturation:brightness:alpha:
• – getRed:green:blue:alpha:
• – getWhite:alpha:
• – getComponents:
• – numberOfComponents

Retrieving Individual Components

• – alphaComponent
• – blackComponent
• – blueComponent
• – brightnessComponent
• – catalogNameComponent
• – colorNameComponent
• – cyanComponent
• – greenComponent
• – hueComponent
• – localizedCatalogNameComponent
• – localizedColorNameComponent
• – magentaComponent
• – redComponent
• – saturationComponent
• – whiteComponent
• – yellowComponent

Working with the Color Space

• – colorSpaceName
• – colorUsingColorSpaceName:
• – colorUsingColorSpaceName:device:
• – colorSpace
• – colorUsingColorSpace:

Changing the Color

• – blendedColorWithFraction:ofColor:
• – colorWithAlphaComponent:
• – highlightWithLevel:
• – shadowWithLevel:

Drawing

• – drawSwatchInRect:
• – set
• – setFill
• – setStroke

Class Methods

alternateSelectedControlColor

Returns the system color used for the face of a selected control.

+ (NSColor *)alternateSelectedControlColor

Return Value

The system color used for the face of a selected control—a control being clicked or dragged. This color can be used where iApp-like highlighting is desired. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + alternateSelectedControlTextColor
• + selectedControlColor

Declared In

NSColor.h

alternateSelectedControlTextColor

Returns the system color used for text in a selected control.

+ (NSColor *)alternateSelectedControlTextColor

Return Value

The system color used for text in a selected control—a control being clicked or dragged. This color can be used where iApp-like highlighting is desired. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + alternateSelectedControlColor
• + selectedControlTextColor

Declared In

NSColor.h

blackColor

Returns an NSColor object whose grayscale value is 0.0 and whose alpha value is 1.0.

+ (NSColor *)blackColor

Return Value

The NSColor object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – blackComponent

Declared In

NSColor.h

blueColor

Returns an NSColor object whose RGB value is 0.0, 0.0, 1.0 and whose alpha value is 1.0.

+ (NSColor *)blueColor

Return Value

The NSColor object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – blueComponent

Declared In

NSColor.h

brownColor

Returns an NSColor object whose RGB value is 0.6, 0.4, 0.2 and whose alpha value is 1.0.

+ (NSColor *)brownColor

Return Value

The NSColor object.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColor.h

clearColor

Returns an NSColor object whose grayscale and alpha values are both 0.0.

+ (NSColor *)clearColor

Return Value

The NSColor object.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColor.h

colorForControlTint:

Returns the NSColor object specified by the given control tint.

+ (NSColor *)colorForControlTint:(NSControlTint)controlTint

Parameters

controlTint

The control tint for which to return an NSColor object. This is one of the tint settings. For more on control tints, see Using the System Control Tint.

Return Value

The NSColor object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + currentControlTint

Declared In

NSColor.h

colorFromPasteboard:

Returns the NSColor currently on the given pasteboard.

+ (NSColor *)colorFromPasteboard:(NSPasteboard *)pasteBoard

Parameters

pasteBoard

The pasteboard from which to return the color.

Return Value

The color currently on the pasteboard or nil if pasteBoard doesn’t contain color data. The returned color’s alpha component is set to 1.0 if ignoresAlpha returns YES.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – writeToPasteboard:

Declared In

NSColor.h

colorWithCalibratedHue:saturation:brightness:alpha:

Creates and returns an NSColor object using the given opacity and HSB color space components.

+ (NSColor *)colorWithCalibratedHue:(CGFloat)hue saturation:(CGFloat)saturation brightness:(CGFloat)brightness alpha:(CGFloat)alpha

Parameters

hue

The hue component of the color object in the HSB color space.

saturation

The saturation component of the color object in the HSB color space.

brightness

The brightness (or value) component of the color object in the HSB color space.

alpha

The opacity value of the color object,

Return Value

The color object.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + colorWithCalibratedRed:green:blue:alpha:
• + colorWithDeviceHue:saturation:brightness:alpha:
• – getHue:saturation:brightness:alpha:

Declared In

NSColor.h

colorWithCalibratedRed:green:blue:alpha:

Creates and returns an NSColor object using the given opacity and RGB components.

+ (NSColor *)colorWithCalibratedRed:(CGFloat)red green:(CGFloat)green blue:(CGFloat)blue alpha:(CGFloat)alpha

Parameters

red

The red component of the color object.

green

The green component of the color object.

blue

The blue component of the color object.

alpha

The opacity value of the color object.

Return Value

The color object.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + colorWithCalibratedHue:saturation:brightness:alpha:
• + colorWithDeviceRed:green:blue:alpha:
• – getRed:green:blue:alpha:

Declared In

NSColor.h

colorWithCalibratedWhite:alpha:

Creates and returns an NSColor object using the given opacity and grayscale value.

+ (NSColor *)colorWithCalibratedWhite:(CGFloat)white alpha:(CGFloat)alpha

Parameters

white

The grayscale value of the color object.

alpha

The opacity value of the color object.

Return Value

The color object.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + colorWithDeviceWhite:alpha:
• – getWhite:alpha:

Declared In

NSColor.h

colorWithCatalogName:colorName:

Creates and returns an NSColor object by finding the color with the specified name in the given catalog.

+ (NSColor *)colorWithCatalogName:(NSString *)listName colorName:(NSString *)colorName

Parameters

listName

The name of the catalog in which to find the specified color; this may be a standard catalog.

colorName

The name of the color. Note that the color must be defined in the named color space to retrieve it with this method.

Return Value

The color object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – catalogNameComponent
• – colorNameComponent
• – localizedCatalogNameComponent

Declared In

NSColor.h

colorWithCIColor:

Converts a Core Image color object to its NSColor equivalent.

+ (NSColor *)colorWithCIColor:(CIColor *)color

Parameters

color

The Core Image color to convert.

Return Value

The NSColor object corresponding to the specified Core Image color.

Discussion

The method raises if the color space and components associated with color are nil or invalid.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSColor.h

colorWithColorSpace:components:count:

Returns an NSColor object created from the specified components of the given color space.

+ (NSColor *)colorWithColorSpace:(NSColorSpace *)space components:(const CGFloat *)components count:(NSInteger)numberOfComponents

Parameters

space

An NSColorSpace object representing a color space. The method raises if this is nil.

components

An array of the components in the specified color space to use to create the NSColor object. The order of these components is determined by the color-space profile, with the alpha component always last. (If you want the created color to be opaque, specify 1.0 for the alpha component.)

numberOfComponents

The number of components in the components array. This should match the number dictated by the specified color space plus one for alpha. This method raises an exception if they do not match.

Return Value

The color object. If space represents a color space that cannot cannot be used with NSColor objects—for example, a “pattern” color space—the method returns nil.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – colorUsingColorSpace:

Declared In

NSColor.h

colorWithDeviceCyan:magenta:yellow:black:alpha:

Creates and returns an NSColor object using the given opacity value and CMYK components.

+ (NSColor *)colorWithDeviceCyan:(CGFloat)cyan magenta:(CGFloat)magenta yellow:(CGFloat)yellow black:(CGFloat)black alpha:(CGFloat)alpha

Parameters

cyan

The cyan component of the color object.

magenta

The magenta component of the color object.

yellow

The yellow component of the color object.

black

The black component of the color object.

alpha

The opacity value of the color object.

Return Value

The color object.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0. In PostScript, this color space corresponds directly to the device-dependent operator setcmykcolor.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – getCyan:magenta:yellow:black:alpha:

Declared In

NSColor.h

colorWithDeviceHue:saturation:brightness:alpha:

Creates and returns an NSColor object using the given opacity value and HSB color space components.

+ (NSColor *)colorWithDeviceHue:(CGFloat)hue saturation:(CGFloat)saturation brightness:(CGFloat)brightness alpha:(CGFloat)alpha

Parameters

hue

The hue component of the color object.

saturation

The saturation component of the color object.

brightness

The brightness component of the color object.

alpha

The opacity value of the color object.

Return Value

The color object.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0. In PostScript, this color space corresponds directly to the device-dependent operator setrgbcolor.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + colorWithCalibratedHue:saturation:brightness:alpha:
• + colorWithDeviceRed:green:blue:alpha:
• – getHue:saturation:brightness:alpha:

Declared In

NSColor.h

colorWithDeviceRed:green:blue:alpha:

Creates and returns an NSColor object using the given opacity value and RGB components.

+ (NSColor *)colorWithDeviceRed:(CGFloat)red green:(CGFloat)green blue:(CGFloat)blue alpha:(CGFloat)alpha

Parameters

red

The red component of the color object.

green

The green component of the color object.

blue

The blue component of the color object.

alpha

The opacity value of the color object.

Return Value

The color object.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0. In PostScript, this color space corresponds directly to the device-dependent operator setrgbcolor.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + colorWithCalibratedRed:green:blue:alpha:
• + colorWithDeviceHue:saturation:brightness:alpha:
• – getRed:green:blue:alpha:

Declared In

NSColor.h

colorWithDeviceWhite:alpha:

Creates and returns an NSColor object using the given opacity and grayscale values.

+ (NSColor *)colorWithDeviceWhite:(CGFloat)white alpha:(CGFloat)alpha

Parameters

white

The grayscale value of the color object.

alpha

The opacity value of the color object.

Return Value

The color object.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0. In PostScript, this color space corresponds directly to the device-dependent operator setgray.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + colorWithCalibratedWhite:alpha:
• – getWhite:alpha:

Declared In

NSColor.h

colorWithPatternImage:

Creates and returns an NSColor object that uses the specified image pattern.

+ (NSColor *)colorWithPatternImage:(NSImage *)image

Parameters

image

The image to use as the pattern for the color object. The image is tiled starting at the bottom of the window. The image is not scaled.

Return Value

The NSColor object. This color object is autoreleased.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColor.h

controlAlternatingRowBackgroundColors

Returns an array containing the system specified background colors for alternating rows in tables and lists.

+ (NSArray *)controlAlternatingRowBackgroundColors

Return Value

An array of NSColor objects specifying the system colors used for rows in tables and lists. You should not assume the array will contain only two colors. For general information on system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSColor.h

controlBackgroundColor

Returns the system color used for the background of large controls.

+ (NSColor *)controlBackgroundColor

Return Value

The system color used for the background of large controls such as browsers, table views, and clip views. For general information on system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColor.h

controlColor

Returns the system color used for the flat surfaces of a control.

+ (NSColor *)controlColor

Return Value

The system color used for the flat surfaces of a control. By default, the control color is a pattern color that will draw the ruled lines for the window background, which is the same as returned by windowBackgroundColor.

If you use controlColor assuming that it is a solid, you may have an incorrect appearance. You should use lightGrayColor in its place.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColor.h

controlDarkShadowColor

Returns the system color used for the dark edge of the shadow dropped from controls.

+ (NSColor *)controlDarkShadowColor

Return Value

Of the two dark borders that run along the bottom and right of controls, representing shadows, the color of the outer, darker border. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + controlShadowColor

Declared In

NSColor.h

controlHighlightColor

Returns the system color used for the highlighted bezels of controls.

+ (NSColor *)controlHighlightColor

Return Value

Of the two light borders that run along the top and left of controls, representing reflections from a light source in the upper left, the color of the inner, duller border. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + controlLightHighlightColor

Declared In

NSColor.h

controlLightHighlightColor

Returns the system color used for light highlights in controls.

+ (NSColor *)controlLightHighlightColor

Return Value

Of the two light borders that run along the top and left of controls, representing reflections from a light source in the upper left, the color of the outer, brighter border. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + controlHighlightColor

Declared In

NSColor.h

controlShadowColor

Returns the system color used for the shadows dropped from controls.

+ (NSColor *)controlShadowColor

Return Value

Of the two dark borders that run along the bottom and right of controls, representing shadows, the color of the inner, lighter border. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + controlDarkShadowColor

Declared In

NSColor.h

controlTextColor

Returns the system color used for text on controls that aren’t disabled.

+ (NSColor *)controlTextColor

Return Value

The color used for text on enabled controls. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + disabledControlTextColor

Declared In

NSColor.h

currentControlTint

Returns the current system control tint.

+ (NSControlTint)currentControlTint

Return Value

The current system control tint.

Discussion

An application can register for the NSControlTintDidChangeNotification notification to be notified of changes to the system control tint.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + colorForControlTint:

Declared In

NSColor.h

cyanColor

Returns an NSColor object whose RGB value is 0.0, 1.0, 1.0 and whose alpha value is 1.0.

+ (NSColor *)cyanColor

Return Value

The NSColor object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – cyanComponent

Declared In

NSColor.h

darkGrayColor

Returns an NSColor object whose grayscale value is 1/3 and whose alpha value is 1.0.

+ (NSColor *)darkGrayColor

Return Value

The NSColor object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + lightGrayColor
• + grayColor

Declared In

NSColor.h

disabledControlTextColor

Returns the system color used for text on disabled controls.

+ (NSColor *)disabledControlTextColor

Return Value

The color used for text on disabled controls. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + controlTextColor

Declared In

NSColor.h

grayColor

Returns an NSColor object whose grayscale value is 0.5 and whose alpha value is 1.0.

+ (NSColor *)grayColor

Return Value

The NSColor object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + lightGrayColor
• + darkGrayColor

Declared In

NSColor.h

greenColor

Returns an NSColor object whose RGB value is 0.0, 1.0, 0.0 and whose alpha value is 1.0.

+ (NSColor *)greenColor

Return Value

The NSColor object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – greenComponent

Declared In

NSColor.h

gridColor

Returns the system color used for the optional gridlines in, for example, a table view.

+ (NSColor *)gridColor

Return Value

The system color used for gridlines. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColor.h

headerColor

Returns the system color used as the background color for header cells in table views and outline views.

+ (NSColor *)headerColor

Return Value

The system color used as the background for header cells in table and outline views. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColor.h

headerTextColor

Returns the system color used for text in header cells in table views and outline views.

+ (NSColor *)headerTextColor

Return Value

The system color used for text in header cells in table and outline views. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColor.h

highlightColor

Returns the system color that represents the virtual light source on the screen.

+ (NSColor *)highlightColor

Return Value

The system color for the virtual light source on the screen.

Discussion

This method is invoked by the highlightWithLevel: method. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – highlightWithLevel:

Declared In

NSColor.h

ignoresAlpha

Returns a Boolean value indicating whether the application supports alpha.

+ (BOOL)ignoresAlpha

Return Value

YES if the application doesn't support alpha; otherwise NO. This value is consulted when an application imports alpha (through color dragging, for instance). The value determines whether the color panel has an opacity slider.

This value is YES by default, indicating that the opacity components of imported colors will be set to 1.0. If an application wants alpha, it can invoke the setIgnoresAlpha: method with a parameter of NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + setIgnoresAlpha:
• – alphaComponent

Declared In

NSColor.h

keyboardFocusIndicatorColor

Returns the system color that represents the keyboard focus ring around controls.

+ (NSColor *)keyboardFocusIndicatorColor

Return Value

The system color representing the focus ring.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColor.h

knobColor

Returns the system color used for the flat surface of a slider knob that hasn’t been selected.

+ (NSColor *)knobColor

Return Value

The system color used for an unselected slider knob.

Discussion

The knob’s beveled edges, which set it in relief, are drawn in highlighted and shadowed versions of the face color. When a knob is selected, its color changes to selectedKnobColor. For general information about system colors, see “Accessing System Colors”.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColor.h

lightGrayColor

Returns an NSColor object whose grayscale value is 2/3 and whose alpha value is 1.0.

+ (NSColor *)lightGrayColor

Return Value

The NSColor object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + grayColor
• + darkGrayColor

Declared In

NSColor.h

magentaColor

Returns an NSColor object whose RGB value is 1.0, 0.0, 1.0 and whose alpha value is 1.0.

+ (NSColor *)magentaColor

Return Value

The NSColor object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – magentaComponent

Declared In

NSColor.h

orangeColor

Returns an NSColor object whose RGB value is 1.0, 0.5, 0.0 and whose alpha value is 1.0.

+ (NSColor *)orangeColor

Return Value

The NSColor object.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColor.h