Class

NSColor

An object that stores color data and sometimes opacity (alpha value).

Overview

Many methods in AppKit require you to specify color data using an NSColor object; when drawing you use them to set the current fill and stroke colors. Color objects are immutable and thread-safe. You can create color objects in many ways:

  • Load colors from an asset catalog. Colors created from assets can adapt automatically to system appearance changes.

  • Use the semantic colors for custom UI elements, so that they match the appearance of other AppKit views; see UI Element Colors.

  • Use the adaptable system colors, such as systemBlueColor, when you want a specific tint that looks correct in both light and dark environments.

  • Create a color object from another object, such as a Core Graphics representation of a color, or a Core Image color.

  • Create a color from an NSImage object, and paint a repeating pattern instead of using a solid color.

  • Create a color by applying a transform to another NSColor object. For example, you might perform a blend operation between two colors, or you might create a color that represents the same color, but in a different color space.

  • Create custom colors using raw component values, and a variety of color spaces, when you need to represent user-specified colors.

For user-specified colors, you can also display a color panel and let the user specify the color. For information about color panels, see NSColorPanel.

Color and Color Spaces

A color object is typically represented internally as a Core Graphics color (CGColorRef) in a Core Graphics color space (CGColorSpaceRef). Colors can also be created in extended color spaces:

extendedSRGBColorSpace

extendedGenericGamma22GrayColorSpace

When you need to worry about color spaces, use extended color spaces as working color spaces. When you need to worry about representing that color as closely as possible in a specific color space, convert the color from the extended color space into the target color space.

When working in an extended color space, color values are not clamped to fit inside the color gamut, meaning that component values may be less than 0.0 or greater than 1.0. When displayed on an sRGB display, such colors are outside the gamut and won't render accurately. However, extended color spaces are useful as working color spaces when you want a pixel format and representation that other color spaces can be easily converted into. For example, a color in the Display P3 color space can convert to an extended sRGB format, even if it isn't within the sRGB color gamut. While some of the converted color's values are outside of the 0-1.0 range, the color renders correctly when viewed on a device with a P3 display gamut.

It is a programmer error to access color components of a color space that the NSColor object does not support. For example, you cannot access the redComponent property and getRed:green:blue:alpha: method on a color that uses the CMYK color space. Further, the getComponents: method and numberOfComponents property work only in color spaces that have individual components. As such, they return the components of color objects as individual floating-point values regardless of whether they’re based on NSColorSpace objects or named color spaces. However, older component-fetching methods such as getRed:green:blue:alpha: are effective only on color objects based on named color spaces.

If you have a color object in an unknown color space and you want to extract its components, convert the color object to a known color space and then use the component accessor methods of that color space.

Topics

Getting and Creating Colors

Get one of the AppKit-defined colors, load colors from asset catalogs, or create custom colors for your app.

UI Element Colors

Retrieve standard color objects for use with windows, controls, labels, text, selections and other content in your app.

Standard Colors

Retrieve the standard color objects for common colors like red, blue, green, black, white, and more.

Color Creation

Load colors from asset catalogs, and create colors from raw component values, such as those used by grayscale, RGB, HSB, and CMYK colors.

Applying a Specific Appearance to a Color

colorWithSystemEffect:

Returns a new color object that represents the current color modified to include the specified visual effect.

Beta
NSColorSystemEffect

Constants for user interactions that change the appearance of a view or control.

Beta

Transforming an Existing Color Object

colorUsingColorSpace:

Creates a new color object representing the color of the receiver in the specified color space.

blendedColorWithFraction:ofColor:

Creates a new color object whose component values are a weighted sum of the receiver’s and the specified color object's.

colorWithAlphaComponent:

Creates a new color object that has the same color space and component values as the receiver, but the specified alpha component.

highlightWithLevel:

Creates a new color object that represents a blend between the current color and the highlight color.

shadowWithLevel:

Creates a new color object that represents a blend between the current color and the shadow color.

colorUsingColorSpaceName:

Creates a new color object whose color is the same as the receiver’s, except that the new NSColor is in the specified color space.

Deprecated
colorUsingColorSpaceName:device:

Creates a new color object for the same color, but in the specified color space and specific to the given device.

Deprecated

Determining the Color's Alpha Support

ignoresAlpha

Returns a Boolean value indicating whether the app supports alpha.

Copying and Pasting Color Information

colorFromPasteboard:

Creates a color object from color data currently on the pasteboard.

writeToPasteboard:

Writes the receiver’s data to the specified pasteboard.

Retrieving Component Values from a Color Object

getCyan:magenta:yellow:black:alpha:

Returns the receiver’s CMYK and opacity values.

getHue:saturation:brightness:alpha:

Returns the receiver’s HSB component and opacity values in the respective arguments.

getRed:green:blue:alpha:

Returns the receiver’s RGB component and opacity values in the respective arguments.

getWhite:alpha:

Returns the grayscale and alpha values of the color.

numberOfComponents

The number of components in the color.

getComponents:

Returns the components of the receiver as an array.

Retrieving Individual Components

alphaComponent

The alpha (opacity) component value of the color.

whiteComponent

The white component value of the color.

redComponent

The red component value of the color.

greenComponent

The green component value of the color.

blueComponent

The blue component value of the color.

cyanComponent

The cyan component value of the color.

magentaComponent

The magenta component value of the color.

yellowComponent

The yellow component value of the color.

blackComponent

The black component value of the color.

hueComponent

The hue component value of the color.

saturationComponent

The saturation component value of the color.

brightnessComponent

The brightness component value of the color.

catalogNameComponent

The catalog containing the color’s name.

localizedCatalogNameComponent

The localized version of the catalog name containing the color.

colorNameComponent

The name of the color.

localizedColorNameComponent

The localized version of the color name.

Working with the Color Space

type

The type of the color object.

colorUsingType:

Returns a version of the color object that is compatible with the specified color type.

NSColorType

Constants indicating the color's type, and which methods may be called on the color object.

colorSpace

The color space associated with the color.

colorSpaceName

The name of the color space associated with the color.

Deprecated
NSColorSpaceName

Color space names.

Retrieving CGColor Information

CGColor

The Core Graphics color object corresponding to the color.

Drawing

drawSwatchInRect:

Draws the current color in the given rectangle.

set

Sets the color of subsequent drawing to the color that the receiver represents.

setFill

Sets the fill color of subsequent drawing to the receiver’s color.

setStroke

Sets the stroke color of subsequent drawing to the receiver’s color.

Determining When Colors Change

NSSystemColorsDidChangeNotification

Sent when the system colors have changed, such as through a system control panel interface.

NSControlTintDidChangeNotification

Sent after the user changes control tint preference.

Deprecated

Initializing a Color Object

init

Initializes the color object.

Getting the Standard Grayscale Colors

NSWhite

A constant that specifies the white shade in the 2-bit deep grayscale color space.

NSLightGray

A constant that specifies the light gray shade in the 2-bit deep grayscale color space.

NSDarkGray

A constant that specifies the dark gray shade in the 2-bit deep grayscale color space.

NSBlack

A constant that specifies the black shade in the 2-bit deep grayscale color space.

Supporting Old Versions of AppKit

NSAppKitVersionNumberWithPatternColorLeakFix

The specific version of the AppKit framework from OS X 10.1 that correctly autoreleases color objects.

See Also

Colors

NSColorList

An ordered list of color objects, identified by keys.

NSColorSpace

An object that represents a custom color spaces.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software