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 can be used safely from multiple threads in your app.Color objects can be created in a variety of ways:

  • AppKit provides standard system colors that you can use to match the colors of your own UI objects to those provided by AppKit. You can use these colors without needing to understand the underlying representation of color.

  • AppKit provides definitions for very basic colors, such as red, orange, yellow, and so on.

  • You can create a custom color in a variety of color spaces.

  • You can create a color object from another object, such as another NSColor object, a Core Graphics representation of a color, or a Core Image color.

  • You can create a color from an NSImage object, which is used to paint a repeating pattern instead of a solid color.

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

Color and Color Spaces

A color object is typically represented internally as a Core Graphics color (CGColor) in a Core Graphics color space (CGColorSpace). There are methods and properties that return the underlying color data. See Retrieving Component Values from aColor Object and Retrieving Individual Components.

Colors can be created in extended color spaces:

extendedSRGB

extendedGenericGamma22Gray

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 will not be rendered accurately. However, extended color spaces are useful 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 that is not within the sRGB color gamut can still be converted to an extended sRGB format. Some of its values will be outside of the 0-1.0 range. However, when displayed on a device with a P3 display gamut, it would still be rendered correctly.

In general, when you need to worry about color spaces, use these 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.

It is invalid to use an accessor method related to components of a particular color space on an NSColor object that does not share the same color space model. For example, the redComponent property and getRed(_:green:blue:alpha:) method work on color objects that use an RGB color space model; if you access the property on a color object in the CMYK color space, an exception is raised. Further, the getComponents(_:) method and numberOfComponents property work in color spaces that have individual components. Thus 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, you should first convert the color object to a known color space before using the component accessor methods of that color space.

Topics

Getting System Colors

class var alternateSelectedControlColor: NSColor

Returns the system color used for the face of a selected control in a list or table.

class var alternateSelectedControlTextColor: NSColor

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

init(for: NSControlTint)

Returns the NSColor object specified by the given control tint.

class var controlBackgroundColor: NSColor

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

class var controlColor: NSColor

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

class var controlAlternatingRowBackgroundColors: [NSColor]

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

class var controlHighlightColor: NSColor

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

class var controlLightHighlightColor: NSColor

Returns the system color used for light highlights in controls.

class var controlShadowColor: NSColor

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

class var controlDarkShadowColor: NSColor

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

class var controlTextColor: NSColor

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

class var currentControlTint: NSControlTint

Returns the current system control tint.

class var disabledControlTextColor: NSColor

Returns the system color used for text on disabled controls.

class var gridColor: NSColor

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

class var headerColor: NSColor

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

class var headerTextColor: NSColor

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

class var highlightColor: NSColor

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

class var keyboardFocusIndicatorColor: NSColor

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

class var knobColor: NSColor

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

class var scrollBarColor: NSColor

Returns the system color used for scroll “bars”—that is, for the groove in which a scroller’s knob moves

class var secondarySelectedControlColor: NSColor

Returns the color used for selected controls in non-key views.

class var selectedControlColor: NSColor

Returns the system color used for the face of a selected control—a control that has been clicked or is being dragged.

class var selectedControlTextColor: NSColor

Returns the system color used for text in a selected control—a control being clicked or dragged.

class var selectedMenuItemColor: NSColor

Returns the system color used for the face of selected menu items.

class var selectedMenuItemTextColor: NSColor

Returns the system color used for the text in menu items.

class var selectedTextBackgroundColor: NSColor

Returns the system color used for the background of selected text.

class var selectedTextColor: NSColor

Returns the system color used for selected text.

class var selectedKnobColor: NSColor

Returns the system color used for the slider knob when it is selected.

class var shadowColor: NSColor

Returns the system color that represents the virtual shadows cast by raised objects on the screen.

class var textBackgroundColor: NSColor

Returns the system color used for the text background.

class var textColor: NSColor

Returns the system color used for text.

class var windowBackgroundColor: NSColor

Returns a pattern color that will draw the ruled lines for the window background.

class var windowFrameColor: NSColor

Returns the system color used for window frames, except for their text.

class var windowFrameTextColor: NSColor

Returns the system color used for the text in window frames.

class var underPageBackgroundColor: NSColor

Returns the color to use when areas revealed behind views.

Creating a Color Object from a Color Stored in a Catalog

init?(named: NSColor.Name)

Creates and returns a color object by finding the color with the specified name in the asset catalog of the main bundle.

init?(named: NSColor.Name, bundle: Bundle?)

Creates and returns a color object by finding the color with the specified name in the asset catalog of the specified bundle.

init?(catalogName: NSColorList.Name, colorName: NSColor.Name)

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

Creating a Custom Color Object from HSB Component Values

init(calibratedHue: CGFloat, saturation: CGFloat, brightness: CGFloat, alpha: CGFloat)

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

init(deviceHue: CGFloat, saturation: CGFloat, brightness: CGFloat, alpha: CGFloat)

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

init(hue: CGFloat, saturation: CGFloat, brightness: CGFloat, alpha: CGFloat)

Creates and returns a color object with the specified hue, saturation, brightness, and alpha channel values.

init(colorSpace: NSColorSpace, hue: CGFloat, saturation: CGFloat, brightness: CGFloat, alpha: CGFloat)

Creates and returns an NSColor object with the specified color space, hue, saturation, brightness, and alpha channel values.

Creating a Custom Color Object from RGB Component Values

init(srgbRed: CGFloat, green: CGFloat, blue: CGFloat, alpha: CGFloat)

Returns a color created from the specified components in the sRGB colorspace.

init(displayP3Red: CGFloat, green: CGFloat, blue: CGFloat, alpha: CGFloat)

Returns a color created from the specified components in the Display P3 colorspace.

init(red: CGFloat, green: CGFloat, blue: CGFloat, alpha: CGFloat)

Creates and returns a color object with the specified red, green, blue, and alpha channel values.

init(calibratedRed: CGFloat, green: CGFloat, blue: CGFloat, alpha: CGFloat)

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

init(deviceRed: CGFloat, green: CGFloat, blue: CGFloat, alpha: CGFloat)

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

Creating a Custom Color Object from White Component Values

init(white: CGFloat, alpha: CGFloat)

Creates and returns a white (or gray) color object with the specified brightness and alpha channel values.

init(calibratedWhite: CGFloat, alpha: CGFloat)

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

init(deviceWhite: CGFloat, alpha: CGFloat)

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

init(genericGamma22White: CGFloat, alpha: CGFloat)

Returns an color created with the specified white and alpha values in the GenericGamma22 colorspace.

Creating a Custom Color Object from CMYK Component Values

init(deviceCyan: CGFloat, magenta: CGFloat, yellow: CGFloat, black: CGFloat, alpha: CGFloat)

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

Creating a Custom Color Object in an Arbitrary Color Space

init(colorSpace: NSColorSpace, components: UnsafePointer<CGFloat>, count: Int)

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

Creating a Color Object from Another Representation of Color

init?(cgColor: CGColor)

Creates and returns a new color using the specified CGColor.

init(ciColor: CIColor)

Converts a Core Image color object to its NSColor equivalent.

Creating a Color Object that Draws Using a Pattern

init(patternImage: NSImage)

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

var patternImage: NSImage

The pattern image used as a color.

Creating Colors By Transforming Other Colors

func usingColorSpaceName(NSColorSpaceName)

Creates and returns an NSColor whose color is the same as the receiver’s, except that the new NSColor is in the specified color space.

func usingColorSpaceName(NSColorSpaceName?, device: [NSDeviceDescriptionKey : Any]?)

Creates and returns an NSColor object whose color is the same as the receiver’s, except that the new NSColor is in the given color space and is specific to the given device.

func usingColorSpace(NSColorSpace)

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

func blended(withFraction: CGFloat, of: NSColor)

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

func withAlphaComponent(CGFloat)

Creates and returns an NSColor object that has the same color space and component values as the receiver, but the specified alpha component.

func highlight(withLevel: CGFloat)

Returns a color object that represents a blend between the receiver and the highlight color returned by highlightColor.

func shadow(withLevel: CGFloat)

Returns a color object that represents a blend between the receiver and the shadow color returned by shadowColor.

Copying and Pasting Color Information

init?(from: NSPasteboard)

Returns the NSColor currently on the given pasteboard.

func write(to: NSPasteboard)

Writes the receiver’s data to the specified pasteboard.

Retrieving Individual Components

var alphaComponent: CGFloat

The alpha (opacity) component value of the color.

var whiteComponent: CGFloat

The white component value of the color.

var redComponent: CGFloat

The red component value of the color.

var greenComponent: CGFloat

The green component value of the color.

var blueComponent: CGFloat

The blue component value of the color.

var cyanComponent: CGFloat

The cyan component value of the color.

var magentaComponent: CGFloat

The magenta component value of the color.

var yellowComponent: CGFloat

The yellow component value of the color.

var blackComponent: CGFloat

The black component value of the color.

var hueComponent: CGFloat

The hue component value of the color.

var saturationComponent: CGFloat

The saturation component value of the color.

var brightnessComponent: CGFloat

The brightness component value of the color.

var catalogNameComponent: NSColorList.Name

The catalog containing the color’s name.

var localizedCatalogNameComponent: String

The localized version of the catalog name containing the color.

var localizedColorNameComponent: String

The localized version of the color name.

Working with the Color Space

var type: NSColor.ColorType

Constants that identify the properties that are valid for a specific color.

var colorSpace: NSColorSpace

The color space associated with the color.

var colorSpaceName: NSColorSpaceName

The name of the color space associated with the color.

Retrieving CGColor Information

var cgColor: CGColor

The Core Graphics color object corresponding to the color.

Drawing

func drawSwatch(in: NSRect)

Draws the current color in the given rectangle.

func set()

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

func setFill()

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

func setStroke()

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

Notifications

class let systemColorsDidChangeNotification: NSNotification.Name

Sent when the system colors have been changed (such as through a system control panel interface).

Type Properties

class var black: NSColor

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

class var blue: NSColor

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

class var brown: NSColor

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

class var clear: NSColor

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

class let currentControlTintDidChangeNotification: NSNotification.Name

Sent after the user changes control tint preference.

class var cyan: NSColor

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

class var darkGray: NSColor

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

class var gray: NSColor

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

class var green: NSColor

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

class var ignoresAlpha: Bool

Returns a Boolean value indicating whether the application supports alpha.

class var labelColor: NSColor

The primary color to use for text in labels.

class var lightGray: NSColor

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

class var magenta: NSColor

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

class var orange: NSColor

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

class var purple: NSColor

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

class var quaternaryLabelColor: NSColor

The quaternary color to use for label text and separators

class var red: NSColor

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

class var secondaryLabelColor: NSColor

The secondary color to use for text in labels.

class var tertiaryLabelColor: NSColor

The tertiary color to use for text in labels.

class var white: NSColor

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

class var yellow: NSColor

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

See Also

Colors

class NSColorList

An ordered list of NSColor objects, identified by keys.

class NSColorSpace

An object that represents a custom color spaces.