Inherits from: NSResponder : NSObject
Conforms to: NSCoding
NSCopying
NSObject (NSObject)
Declared in: AppKit/NSColor.h
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.
Various colorWith... and colorUsing... methods.Preset colors: blackColor, blueColor, etc.
colorUsingColorSpaceName: | Creates an NSColor in the specified color space. |
set | Sets the drawing color. |
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 PostScript drawing context. This causes subsequently drawn graphics to have the color represented by the NSColor instance.
A color is defined in some particular color space. A color space consists of a set of dimensions-such as red, green, and blue in the case of RGB space. Each point in the space represents a unique color, and the point's location along each dimension is called a component. An individual color is usually specified by the numeric values of its components, which range from 0.0 to 1.0. For instance, a pure red is specified in RGB space by the component values 1.0, 0.0, and 0.0.
Some color spaces include an alpha component, which defines the color's opacity. An alpha value of 1.0 means completely opaque, and 0.0 means completely transparent. The alpha component is ignored when the color is used on a device that doesn't support alpha, such as a printer.
There are three kinds of color spaces in the Application Kit:
NSColors provided by the Application Kit use eight different color spaces, referred to by these global NSString variables:
Global Variable | Color Space Description |
NSDeviceCMYKColorSpace |
Cyan, magenta, yellow, black, and alpha components |
NSDeviceWhiteColorSpace |
White and alpha components |
NSDeviceBlackColorSpace |
Black and alpha components |
NSDeviceRGBColorSpace |
Red, green, blue, and alpha componentsHue, saturation, brightness, and alpha components |
NSCalibratedWhiteColorSpace |
White and alpha components |
NSCalibratedBlackColorSpace |
Black and alpha components |
NSCalibratedRGBColorSpace |
Red, green, blue, and alpha componentsHue, saturation, brightness, and alpha components |
NSNamedColorSpace |
Catalog name and color name components |
Color spaces whose names start with "NSDevice" are device-dependent; those whose names start with "NSCalibrated" are device-independent.
There's usually no need to retrieve the individual components
of a color, but when needed, you can retrieve either a set of components
(using such methods as getRed:green:blue:alpha:)
or an individual component (using such methods as redComponent). However,
it's illegal to ask an NSColor for components that aren't defined
for its color space. You can identify the color space by sending
a colorSpaceName message
to the NSColor object. If you need to ask an NSColor for components
that aren't in its color space (for instance, when you've gotten
the color from the color panel), first convert the color to the
appropriate color space using the colorUsingColorSpaceName: method.
If the color is already in the specified color space, you get the
same color back; otherwise you get a conversion that's usually
lossy or that's correct only for the current device. You get back nil
if
the specified conversion can't be done.
Subclasses of NSColor need to implement the colorSpaceName and set methods, as well as the methods that return the components for that color space and the methods in the NSCoding protocol. Some other methods-such as colorWithAlphaComponent:, isEqual:, and colorUsingColorSpaceName:device:-may also be implemented if they make sense for the color space. Mutable subclasses (if any) should additionally implement copyWithZone: to provide a true copy.
NSColor has a number of methods which return "system" colors; colors that are controlled by user preferences. These colors-including controlColor, textColor, and selectedTextColor-should be used by developers who want to create custom controls or subclass existing controls while honoring the user's color preferences. System colors are implemented as named colors in a special color list named "System." To extract the components of a system color, you must use NSColor's colorUsingColorSpaceName: method to convert the color to a color space known to respond to the component accessor methods you need.
An NSSystemColorsDidChangeNotification is sent when the system colors have been changed (such as through a system control panel interface). If you have any non-system colors that depend on the system colors, you can change them when you receive this notification.
- NSCoding
- - encodeWithCoder:
- - initWithCoder:
- NSCopying
- - copyWithZone:
- 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:
- Creating an NSColor With Preset Components
- + blackColor
- + blueColor
- + brownColor
- + clearColor
- + cyanColor
- + darkGrayColor
- + grayColor
- + greenColor
- + lightGrayColor
- + magentaColor
- + orangeColor
- + purpleColor
- + redColor
- + whiteColor
- + yellowColor
- Creating a system color-an NSColor whose value is specified by user preferences
- + controlBackgroundColor
- + controlColor
- + controlHighlightColor
- + controlLightHighlightColor
- + controlShadowColor
- + controlDarkShadowColor
- + controlTextColor
- + disabledControlTextColor
- + gridColor
- + highlightColor
- + knobColor
- + scrollBarColor
- + selectedControlColor
- + selectedControlTextColor
- + selectedMenuItemColor
- + selectedMenuItemTextColor
- + selectedTextBackgroundColor
- + selectedTextColor
- + selectedKnobColor
- + shadowColor
- + textBackgroundColor
- + textColor
- + 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:
- Retrieving Individual Components
- - alphaComponent
- - blackComponent
- - blueComponent
- - brightnessComponent
- - catalogNameComponent
- - colorNameComponent
- - cyanComponent
- - greenComponent
- - hueComponent
- - localizedCatalogNameComponent
- - l ocalizedColorNameComponent
- - magentaComponent
- - redComponent
- - saturationComponent
- - whiteComponent
- - yellowComponent
- Converting to Another Color Space
- - colorSpaceName
- - colorUsingColorSpaceName:
- - colorUsingColorSpaceName:device:
- Changing the Color
- - blendedColorWithFraction:ofColor:
- - colorWithAlphaComponent:
- - highlightWithLevel:
- - shadowWithLevel:
- Drawing
- - drawSwatchInRect:
- - set
+ (NSColor *)blackColor
See Also: - blackComponent
+ (NSColor *)blueColor
NSCalibratedRGBColorSpace
whose
RGB value is 0.0, 0.0, 1.0 and whose alpha value is 1.0.See Also: - blueComponent
+ (NSColor *)brownColor
NSCalibratedRGBColorSpace
whose
RGB value is 0.6, 0.4, 0.2 and whose alpha value is 1.0.+ (NSColor *)clearColor
NSCalibratedWhiteColorSpace
whose
grayscale and alpha values are both 0.0.+ (NSColor *)colorFromPasteboard:(NSPasteboard
*)pasteBoard
nil
if
the pasteboard doesn't contain color data. The
returned color's alpha component is set to 1.0 if ignoresAlpha returns YES
.See Also: - writeToPasteboard:
+ (NSColor *)colorWithCalibratedHue:(float)hue saturation:(float)saturation brightness:(float)brightness alpha:(float)alpha
NSCalibratedRGBColorSpace
,
whose opacity value is alpha, and
whose components in HSB space would be hue, saturation,
and brightness. (Values
below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted
as 1.0.)See Also: + colorWithCalibratedRed:green:blue:alpha:, + colorWithDeviceHue:saturation:brightness:alpha:, - getHue:saturation:brightness:alpha:
+ (NSColor *)colorWithCalibratedRed:(float)red green:(float)green blue:(float)blue alpha:(float)alpha
NSCalibratedRGBColorSpace
,
whose opacity value is alpha, and
whose RGB components are red, green,
and blue. (Values
below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted
as 1.0.)See Also: + colorWithCalibratedHue:saturation:brightness:alpha:, + colorWithDeviceRed:green:blue:alpha:, - getRed:green:blue:alpha:
+ (NSColor *)colorWithCalibratedWhite:(float)white alpha:(float)alpha
NSCalibratedWhiteColorSpace
,
whose opacity value is alpha, and
whose grayscale value is white. (Values
below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted
as 1.0.)See Also: + colorWithDeviceWhite:alpha:, - getWhite:alpha:
+ (NSColor *)colorWithCatalogName:(NSString
*)listName colorName:(NSString
*)colorName
NSNamedColorSpace
,
by finding the color named colorName in
the catalog named listName, which
may be a standard catalog.See Also: - catalogNameComponent, - colorNameComponent, - localizedCatalogNameComponent
+ (NSColor *)colorWithDeviceCyan:(float)cyan magenta:(float)magenta yellow:(float)yellow black:(float)black alpha:(float)alpha
NSDeviceCMYKColorSpace
, whose
opacity value is alpha, and whose
CMYK components are cyan, magenta, yellow,
and black. (Values
below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted
as 1.0.) In PostScript, this colorspace corresponds directly to
the device-dependent operator setcmykcolor
.See Also: - getCyan:magenta:yellow:black:alpha:
+ (NSColor *)colorWithDeviceHue:(float)hue saturation:(float)saturation brightness:(float)brightness alpha:(float)alpha
NSDeviceRGBColorSpace
, whose
opacity value is alpha, and whose
components in HSB space would be hue, saturation,
and brightness. (Values
below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted
as 1.0.) In PostScript, this colorspace corresponds directly to
the device-dependent operator setrgbcolor
.See Also: + colorWithCalibratedHue:saturation:brightness:alpha:, + colorWithDeviceRed:green:blue:alpha:, - getHue:saturation:brightness:alpha:
+ (NSColor *)colorWithDeviceRed:(float)red green:(float)green blue:(float)blue alpha:(float)alpha
NSDeviceRGBColorSpace
, whose
opacity value is alpha, and whose
RGB components are red, green,
and blue. (Values
below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted
as 1.0.) In PostScript, this colorspace corresponds directly to
the device-dependent operator setrgbcolor
.See Also: + colorWithCalibratedRed:green:blue:alpha:, + colorWithDeviceHue:saturation:brightness:alpha:, - getRed:green:blue:alpha:
+ (NSColor *)colorWithDeviceWhite:(float)white alpha:(float)alpha
NSDeviceWhiteColorSpace
,
whose opacity value is alpha, and
whose grayscale value is white. (Values
below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted
as 1.0.) In PostScript, this colorspace corresponds directly to
the device-dependent operator setgray
.See Also: + colorWithCalibratedWhite:alpha:, - getWhite:alpha:
+ (NSColor *)controlBackgroundColor
COLOR_WINDOW
on
Windows. For general information on system colors, see System Colors.+ (NSColor *)controlColor
COLOR_3DFACE
in
Windows. A control's beveled edges, which set it in relief, are
drawn in the colors returned by controlShadowColor, controlDarkShadowColor, controlHighlightColor and controlLightHighlightColor.
When a control is selected-that is, clicked or dragged-it changes
to the color returned by selectedControlColor. The return value of controlColor is also the system color used for window backgrounds. For general information about system colors, see System Colors.
+ (NSColor *)controlDarkShadowColor
COLOR_3DDKSHADOW
on
Windows. For general information about system colors, see System Colors.See Also: + controlShadowColor
+ (NSColor *)controlHighlightColor
COLOR_3DLIGHT
on
Windows. For general information about system colors, see System Colors.See Also: + controlLightHighlightColor
+ (NSColor *)controlLightHighlightColor
COLOR_3DHILIGHT
on
Windows. For general information about system colors, see System Colors.See Also: + controlHighlightColor
+ (NSColor *)controlShadowColor
COLOR_3DSHADOW
on
Windows. For general information about system colors, see System Colors.See Also: + controlDarkShadowColor
+ (NSColor *)controlTextColor
COLOR_BTNTEXT
on
Windows. For general information about system colors, see System Colors.See Also: + disabledControlTextColor
+ (NSColor *)cyanColor
NSCalibratedRGBColorSpace
whose
RGB value is 0.0, 1.0, 1.0 and whose alpha value is 1.0.See Also: - cyanComponent
+ (NSColor *)darkGrayColor
NSCalibratedWhiteColorSpace
whose
grayscale value is 1/3 and whose alpha value is 1.0.See Also: + lightGrayColor, + grayColor
+ (NSColor *)disabledControlTextColor
COLOR_3DSHADOW
on
Windows. For general information about system colors, see System Colors.See Also: + controlTextColor
+ (NSColor *)grayColor
NSCalibratedWhiteColorSpace
whose
grayscale value is 0.5 and whose alpha value is 1.0.See Also: + lightGrayColor, + darkGrayColor
+ (NSColor *)greenColor
NSCalibratedRGBColorSpace
whose
RGB value is 0.0, 1.0, 0.0 and whose alpha value is 1.0.See Also: - greenComponent
+ (NSColor *)gridColor
COLOR_3DFACE
on Windows.
For general information about system colors, see System Colors.+ (NSColor *)highlightColor
COLOR_3DHILIGHT
on Windows.
This method is invoked by the highlightWithLevel: method. For general
information about system colors, see System Colors.See Also: - highlightWithLevel:
+ (BOOL)ignoresAlpha
YES
if
the application doesn't support alpha. 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
.See Also: + setIgnoresAlpha:, - alphaComponent
+ (NSColor *)keyboardFocusIndicatorColor
+ (NSColor *)knobColor
COLOR_3DFACE
on
Windows. 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 System
Colors.+ (NSColor *)lightGrayColor
NSCalibratedWhiteColorSpace
whose
grayscale value is 2/3 and whose alpha value is 1.0.See Also: + grayColor, + darkGrayColor
+ (NSColor *)magentaColor
NSCalibratedRGBColorSpace
whose
RGB value is 1.0, 0.0, 1.0 and whose alpha value is 1.0.See Also: - magentaComponent
+ (NSColor *)orangeColor
NSCalibratedRGBColorSpace
whose
RGB value is 1.0, 0.5, 0.0 and whose alpha value is 1.0.+ (NSColor *)purpleColor
NSCalibratedRGBColorSpace
whose
RGB value is 0.5, 0.0, 0.5 and whose alpha value is 1.0.+ (NSColor *)redColor
See Also: - redComponent
+ (NSColor *)scrollBarColor
COLOR_SCROLLBAR
on
Windows. On Windows, when a scroll bar is dragged, its color changes
to the return value of selectedControlColor;
on the Macintosh, however, its color does not change. For general
information about system colors, see System Colors.+ (NSColor *)selectedControlColor
COLOR_HIGHLIGHT
on
Windows. For general information about system colors, see System Colors.See Also: + selectedControlTextColor
+ (NSColor *)selectedControlTextColor
COLOR_HIGHLIGHTTEXT
on
Windows. For general information about system colors, see System Colors.See Also: + selectedControlColor
+ (NSColor *)selectedKnobColor
COLOR_HIGHLIGHT
on
Windows. For general information about system colors, see System Colors.See Also: + knobColor
+ (NSColor *)selectedMenuItemColor
COLOR_HIGHLIGHT
on
Windows. For general information about system colors, see System Colors.See Also: + selectedMenuItemTextColor
+ (NSColor *)selectedMenuItemTextColor
COLOR_HIGHLIGHTTEXT
on
Windows. For general information about system colors, see System Colors.See Also: + selectedMenuItemColor
+ (NSColor *)selectedTextBackgroundColor
COLOR_HIGHLIGHT
on
Windows. For general information about system colors, see System Colors.See Also: + selectedTextColor
+ (NSColor *)selectedTextColor
COLOR_HIGHLIGHTTEXT
on
Windows. For general information about system colors, see System Colors.See Also: + selectedTextBackgroundColor
+ (void)setIgnoresAlpha:(BOOL)flag
YES
,
the application won't support alpha. In this case, no opacity slider
is displayed in the color panel, and colors dragged in or pasted
have their alpha values set to 1.0. By default, applications ignore
alpha. Applications that need to import alpha can invoke this method
with flag set to NO
and
explicitly make colors opaque in cases where it matters to them.See Also: + ignoresAlpha, - alphaComponent
+ (NSColor *)shadowColor
COLOR_3DDKSHADOW
on Windows.
For general information about system colors, see System Colors.See Also: - shadowWithLevel:
+ (NSColor *)textBackgroundColor
COLOR_WINDOW
on
Windows. When text is selected, its background color changes to
the return value of selectedTextBackgroundColor.
For general information about system colors, see System Colors.See Also: + textColor
+ (NSColor *)textColor
COLOR_WINDOWTEXT
on Windows.
When text is selected, its background color changes to the return
value of selectedTextColor.
For general information about system colors, see System Colors.See Also: + textBackgroundColor
+ (NSColor *)whiteColor
NSCalibratedWhiteColorSpace
whose
grayscale and alpha values are both 1.0.See Also: - whiteComponent
+ (NSColor *)windowFrameColor
COLOR_ACTIVEBORDER
on Windows.
For general information about system colors, see System Colors.See Also: + windowFrameTextColor
+ (NSColor *)windowFrameTextColor
COLOR_CAPTIONTEXT
on
Windows. For general information about system colors, see System Colors.See Also: + windowFrameColor
+ (NSColor *)yellowColor
NSCalibratedRGBColorSpace
whose
RGB value is 1.0, 1.0, 0.0 and whose alpha value is 1.0.See Also: - yellowComponent
- (float)alphaComponent
See Also: - getCyan:magenta:yellow:black:alpha:, - getHue:saturation:brightness:alpha:, - getRed:green:blue:alpha:, - getWhite:alpha:
- (float)blackComponent
See Also: - getCyan:magenta:yellow:black:alpha:
- (NSColor *)blendedColorWithFraction:(float)fractiono fColor:(NSColor
*)color
NSCalibratedRGBColorSpace
whose component
values are a weighted sum of the receiver's and color's. The
method converts color and a copy
of the receiver to RGB, and then sets each component of the returned
color to fraction of color's
value plus 1 - fraction of the receiver's.
Returns nil
if the colors
can't be converted to NSCalibratedRGBColorSpace
.- (float)blueComponent
See Also: - getRed:green:blue:alpha:
- (float)brightnessComponent
See Also: - getHue:saturation:brightness:alpha:
- (NSString *)catalogNameComponent
NSNamedColorSpace
.See Also: + colorWithCatalogName:colorName:, - colorNameComponent, - localizedCatalogNameComponent
- (NSString *)colorNameComponent
NSNamedColorSpace
.See Also: + colorWithCatalogName:colorName:, - catalogNameComponent, - localizedCatalogNameComponent
- (NSString *)colorSpaceName
See Also: - colorUsingColorSpaceName:, - colorUsingColorSpaceName:device:
- (NSColor *)colorUsingColorSpaceName:(NSString
*)colorSpace
nil
,
the most appropriate color space is used.Returns nil
if
the specified conversion cannot be done.
See Also: - colorSpaceName
- (NSColor *)colorUsingColorSpaceName:(NSString
*)colorSpace device:(NSDictionary
*)deviceDescription
nil
,
the most appropriate color space is used.If deviceDescription is nil
,
the current device (as obtained from the currently lockFocus'ed
view's window or, if printing, the current printer) is used.
Returns nil
if
the specified conversion cannot be done.
See Also: - colorSpaceName, - colorUsingColorSpaceName:
- (NSColor *)colorWithAlphaComponent:(float)alpha
See Also: - alphaComponent, - blendedColorWithFraction:ofColor:
- (float)cyanComponent
See Also: - getCyan:magenta:yellow:black:alpha:
- (void)drawSwatchInRect:(NSRect)rect
- (void)getCyan:(float
*)cyan magenta:(float
*)magenta yellow:(float
*)yellow black:(float
*)black alpha:(float *)alpha
nil
is
passed in as an argument, the method doesn't set that value. Raises
an exception if the receiver isn't a CMYK color.See Also: - alphaComponent, - blackComponent, - cyanComponent, - magentaComponent, - yellowComponent
- (void)getHue:(float
*)hue saturation:(float *)saturation brightness:(float
*)brightness alpha:(float *)alpha
nil
is
passed in as an argument, the method doesn't set that value. Raises
an exception if the receiver isn't an RGB color.See Also: - alphaComponent, - brightnessComponent, - hueComponent, - saturationComponent
- (void)getRed:(float
*)red green:(float
*)green blue:(float
*)blue alpha:(float
*)alpha
nil
is
passed in as an argument, the method doesn't set that value. Raises
an exception if the receiver isn't an RGB color.See Also: - alphaComponent, - blueComponent, - greenComponent, - redComponent
- (void)getWhite:(float
*)white alpha:(float
*)alpha
nil
is
passed in as an argument, the method doesn't set that value. Raises
an exception if the receiver isn't a grayscale color.See Also: - alphaComponent, - whiteComponent
- (float)greenComponent
See Also: - getRed:green:blue:alpha:
- (NSColor *)highlightWithLevel:(float)highlightLevel
NSCalibratedRGBColorSpace
that
represents a blend between the receiver and the highlight color
returned by highlightColor. The highlight
color's contribution to the blend depends on highlightLevel,
which should be a number between 0.0 and 1.0. (A highlightLevel below
0.0 is interpreted as 0.0; a highlightLevel above
1.0 is interpreted as 1.0.)Returns nil
if
the colors can't be converted to NSCalibratedRGBColorSpace
. Invoke
this method when you want to brighten the receiving NSColor for
use in highlights.
See Also: - shadowWithLevel:
- (float)hueComponent
See Also: - getHue:saturatio, n:brightness:alpha:
- (NSString *)localizedCatalogNameComponent
See Also: + colorWithCatalogName:colorName:, - colorNameComponent
- (NSString *)localizedColorNameComponent
See Also: + colorWithCatalogName:colorName:, - catalogNameComponent, - colorNameComponent, - localizedCatalogNameComponent
- (float)magentaComponent
See Also: - getCyan:magenta:yellow:black:alpha:
- (float)redComponent
See Also: - getRed:green:blue:alpha:
- (float)saturationComponent
See Also: - getHue:saturation:brightness:alpha:
- (void)set
- (NSColor *)shadowWithLevel:(float)shadowLevel
NSCalibratedRGBColorSpace
that
represents a blend between the receiver and the shadow color returned
by shadowColor. The shadow
color's contribution to the blend depends on shadowLevel,
which should be a number between 0.0 and 1.0. (A shadowLevel below
0.0 is interpreted as 0.0; a shadowLevel above
1.0 is interpreted as 1.0.)Returns nil
if
the colors can't be converted to NSCalibratedRGBColorSpace
. Invoke
this method when you want to darken the receiving NSColor for use
in shadows.
See Also: - highlightWithLevel:
- (float)whiteComponent
See Also: - getWhite:alpha:
- (void)writeToPasteboard:(NSPasteboard
*)pasteBoard
See Also: + colorFromPasteboard:
- (float)yellowComponent
See Also: - getCyan:magenta:yellow:black:alpha:
Sent when the system colors have been changed (such as through a system control panel interface).
This notification contains no notification object and no userInfo dictionary.