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 (CGColor​Space). 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 red​Component property and get​Red(_:​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 get​Components(_:​) method and number​Of​Components 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 NSColor​Space objects or named color spaces. However, older component-fetching methods such as get​Red(_:​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 a System Color

class var alternate​Selected​Control​Color:​ NSColorclass var alternate​Selected​Control​Text​Color:​ NSColor
init(for:​ NSControl​Tint)

Returns the NSColor object specified by the given control tint.

class var control​Background​Color:​ NSColorclass var control​Color:​ NSColorclass var control​Alternating​Row​Background​Colors:​ [NSColor]class var control​Highlight​Color:​ NSColorclass var control​Light​Highlight​Color:​ NSColorclass var control​Shadow​Color:​ NSColorclass var control​Dark​Shadow​Color:​ NSColorclass var control​Text​Color:​ NSColorclass var current​Control​Tint:​ NSControl​Tintclass var disabled​Control​Text​Color:​ NSColorclass var grid​Color:​ NSColorclass var header​Color:​ NSColorclass var header​Text​Color:​ NSColorclass var highlight​Color:​ NSColorclass var keyboard​Focus​Indicator​Color:​ NSColorclass var knob​Color:​ NSColorclass var scroll​Bar​Color:​ NSColorclass var secondary​Selected​Control​Color:​ NSColorclass var selected​Control​Color:​ NSColorclass var selected​Control​Text​Color:​ NSColorclass var selected​Menu​Item​Color:​ NSColorclass var selected​Menu​Item​Text​Color:​ NSColorclass var selected​Text​Background​Color:​ NSColorclass var selected​Text​Color:​ NSColorclass var selected​Knob​Color:​ NSColorclass var shadow​Color:​ NSColorclass var text​Background​Color:​ NSColorclass var text​Color:​ NSColorclass var window​Background​Color:​ NSColorclass var window​Frame​Color:​ NSColorclass var window​Frame​Text​Color:​ NSColorclass var under​Page​Background​Color:​ NSColor

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

init?(catalog​Name:​ String, color​Name:​ 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(calibrated​Hue:​ CGFloat, saturation:​ CGFloat, brightness:​ CGFloat, alpha:​ CGFloat)

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

init(device​Hue:​ 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(color​Space:​ NSColor​Space, 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(srgb​Red:​ CGFloat, green:​ CGFloat, blue:​ CGFloat, alpha:​ CGFloat)

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

init(display​P3Red:​ 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(calibrated​Red:​ CGFloat, green:​ CGFloat, blue:​ CGFloat, alpha:​ CGFloat)

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

init(device​Red:​ 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(calibrated​White:​ CGFloat, alpha:​ CGFloat)

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

init(device​White:​ CGFloat, alpha:​ CGFloat)

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

init(generic​Gamma22White:​ 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(device​Cyan:​ 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(color​Space:​ NSColor​Space, components:​ Unsafe​Pointer<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?(cg​Color:​ CGColor)

Creates and returns a new color using the specified CGColor.

init(ci​Color:​ CIColor)

Converts a Core Image color object to its NSColor equivalent.

Creating a NSColor Object that Draws Using a Pattern

init(pattern​Image:​ NSImage)

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

var pattern​Image:​ NSImage

The pattern image used as a color.

Creating Colors By Transforming Other Colors

func using​Color​Space​Name(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 using​Color​Space​Name(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 using​Color​Space(NSColor​Space)

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

func blended(with​Fraction:​ 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 with​Alpha​Component(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(with​Level:​ CGFloat)

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

func shadow(with​Level:​ CGFloat)

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

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 alpha​Component:​ CGFloat

The alpha (opacity) component value of the color.

var white​Component:​ CGFloat

The white component value of the color.

var red​Component:​ CGFloat

The red component value of the color.

var green​Component:​ CGFloat

The green component value of the color.

var blue​Component:​ CGFloat

The blue component value of the color.

var cyan​Component:​ CGFloat

The cyan component value of the color.

var magenta​Component:​ CGFloat

The magenta component value of the color.

var yellow​Component:​ CGFloat

The yellow component value of the color.

var black​Component:​ CGFloat

The black component value of the color.

var hue​Component:​ CGFloat

The hue component value of the color.

var saturation​Component:​ CGFloat

The saturation component value of the color.

var brightness​Component:​ CGFloat

The brightness component value of the color.

var catalog​Name​Component:​ String

The catalog containing the color’s name.

var localized​Catalog​Name​Component:​ String

The localized version of the catalog name containing the color.

var localized​Color​Name​Component:​ String

The localized version of the color name.

Working with the Color Space

var color​Space:​ NSColor​Space

The color space associated with the color.

var color​Space​Name:​ String

The name of the color space associated with the color.

Retrieving CGColor Information

var cg​Color:​ CGColor

The Core Graphics color object corresponding to the color.

Drawing

func draw​Swatch(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 set​Fill()

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

func set​Stroke()

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.

App​Kit Versions for NSColor Bug Fixes

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

Notifications

static let NSSystem​Colors​Did​Change:​ NSNotification.Name

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