Class

NSColor

A NSColor object stores color data and sometimes opacity (alpha value). Many methods in AppKit require you to specify color data using a 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.

Overview

NSColor 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 a 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 NSColor 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 an NSColor object and Retrieving Individual Components.

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 spaces model. If you send such a message to an NSColor 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 NSColor 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 only effective on NSColor objects based on named color spaces.

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.

Symbols

Creating an NSColor Object from a Color Stored in a Color Catalog

init?(catalogName: String, colorName: String)

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

Creating a Custom NSColor 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 an NSColor 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 NSColor 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 an NSColor 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 NSColor Object from White Component Values

init(white: CGFloat, alpha: CGFloat)

Creates and returns a white (or grey) NSColor 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 NSColor 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 NSColor 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 an NSColor 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 NSColor 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(String)

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(String?, device: [String : 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: String

The catalog containing the color’s name.

var localizedCatalogNameComponent: String

The localized version of the catalog name containing the color.

var colorNameComponent: String

The name of the color.

var localizedColorNameComponent: String

The localized version of the color name.

Working with the Color Space

var colorSpace: NSColorSpace

The color space associated with the color.

var colorSpaceName: String

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.

Constants

For definitions of NSColor constants, as well as a discussion of their usage, see “About Color Spaces” in Color Programming Topics.

AppKit Versions for NSColor Bug Fixes

The version of the AppKit framework containing a specific bug fix.

Notifications

static let NSSystemColorsDidChange: NSNotification.Name

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

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