ADC Home > Reference Library > Reference > Legacy Documents > Cocoa > Application Kit Reference for Java (Legacy) >

Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

NSColor

Inherits from
Implements
Package
com.apple.cocoa.application
Companion guide

Class at a Glance

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.

Principal Attributes

Creation

Commonly Used Methods

colorUsingColorSpaceName

Creates an NSColor in the specified color space.

set

Sets the drawing color.

Overview

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 drawing context. Setting the color causes subsequently drawn graphics to have the color represented by the NSColor instance.

It is invalid to use an accessor method related to components of a particular color space on an NSColor object that is not in that color space. For example, methods such as redComponent work on color objects in the calibrated and device RGB color spaces. If you send such a message to an NSColor object in the CMYK color space, an exception is raised. 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.

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

Tasks

Constructors

Creating an NSColor Object from Component Values

Creating an NSColor with Preset Components

Working with Pattern Images

Creating a System Color—an NSColor Whose Value Is Specified by User Preferences

Ignoring Alpha Components

Copying and Pasting

Retrieving a Set of Components

Retrieving Individual Components

Working with the Color Space

Changing the Color

Drawing

Constructors

NSColor

Creates an empty NSColor.

public NSColor()

Static Methods

alternateSelectedControlColor

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

public static NSColor alternateSelectedControlColor()

Discussion

For use where iApp-like highlighting is desired. For general information about system colors, see “Accessing System Colors”.

Availability
See Also

alternateSelectedControlTextColor

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

public static NSColor alternateSelectedControlTextColor()

Discussion

or use where iApp-like highlighting is desired. For general information about system colors, see “Accessing System Colors”.

Availability
See Also

blackColor

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

public static NSColor blackColor()

See Also

blueColor

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

public static NSColor blueColor()

See Also

brownColor

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

public static NSColor brownColor()

clearColor

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

public static NSColor clearColor()

colorForControlTint

Returns the NSColor specified by controlTint, which is one of the tint settings.

public static NSColor colorForControlTint(int controlTint)

colorFromPasteboard

Returns the NSColor currently on pasteBoard, or null if pasteBoard doesn’t contain color data.

public static NSColor colorFromPasteboard(NSPasteboard pasteBoard)

Discussion

The returned color’s alpha component is set to 1.0 if ignoresAlpha returns true.

See Also

colorWithCalibratedHSB

Creates and returns an NSColor whose opacity value is alpha and whose components in HSB space would be hue, saturation, and brightness.

public static NSColor colorWithCalibratedHSB(float hue, float saturation, float brightness, float alpha)

Discussion

(Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.)

See Also

colorWithCalibratedRGB

Creates and returns an NSColor whose opacity value is alpha and whose RGB components are red, green, and blue.

public static NSColor colorWithCalibratedRGB(float red, float green, float blue, float alpha)

Discussion

(Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.)

See Also

colorWithCalibratedWhite

Creates and returns an NSColor whose opacity value is alpha and whose grayscale value is white.

public static NSColor colorWithCalibratedWhite(float white, float alpha)

Discussion

(Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.)

See Also

colorWithCatalogName

Creates and returns an NSColor by finding the color named colorName in the catalog named listName, which may be a standard catalog.

public static NSColor colorWithCatalogName(String listName, String colorName)

Discussion

Note that the color must be defined in the named color space to retrieve it with this method.

See Also

colorWithColorSpace

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

public static NSColor colorWithColorSpace(NSColorSpace space, float[] components)

Discussion

. space must be a NSColorSpace object representing a color space. The number of components in the components array should match the number dictated by the specified color space plus one for alpha. Throws an exception if they do not match. The order of the components is determined by the color-space profile, with the alpha component always last. (If you want the created color to be opaque, specify 1.0 for the alpha component.) If space represents a color space that cannot cannot be used with NSColor objects—for example, a “pattern” color space—the method returns null.

Availability
See Also

colorWithDeviceCMYK

Creates and returns an NSColor whose opacity value is alpha and whose CMYK components are cyan, magenta, yellow, and black.

public static NSColor colorWithDeviceCMYK(float cyan, float magenta, float yellow, float black, float alpha)

Discussion

(Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.) In PostScript, this color space corresponds directly to the device-dependent operator setcmykcolor.

colorWithDeviceHSB

Creates and returns an NSColor whose opacity value is alpha and whose components in HSB space would be hue, saturation, and brightness.

public static NSColor colorWithDeviceHSB(float hue, float saturation, float brightness, float alpha)

Discussion

(Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.) In PostScript, this color space corresponds directly to the device-dependent operator setrgbcolor.

See Also

colorWithDeviceRGB

Creates and returns an NSColor whose opacity value is alpha and whose RGB components are red, green, and blue.

public static NSColor colorWithDeviceRGB(float red, float green, float blue, float alpha)

Discussion

(Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.) In PostScript, this color space corresponds directly to the device-dependent operator setrgbcolor.

See Also

colorWithDeviceWhite

Creates and returns an NSColor whose opacity value is alpha and whose grayscale value is white.

public static NSColor colorWithDeviceWhite(float white, float alpha)

Discussion

(Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.) In PostScript, this color space corresponds directly to the device-dependent operator setgray.

See Also

colorWithPatternImage

Creates and returns an NSColor that uses the pattern in image.

public static NSColor colorWithPatternImage(NSImage image)

Discussion

The image is tiled starting at the bottom of the window. The image is not scaled.

controlAlternatingRowBackgroundColors

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

public static NSArray controlAlternatingRowBackgroundColors()

Discussion

You should not assume the array will contain only two colors. For general information on system colors, see “Accessing System Colors”.

Availability

controlBackgroundColor

Returns the system color used for the background of large controls such as browsers, table views, and clip views.

public static NSColor controlBackgroundColor()

Discussion

For general information on system colors, see “Accessing System Colors”.

controlColor

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

public static NSColor controlColor()

Discussion

By default, the control color is a pattern color that will draw the ruled lines for the window background.

If you use controlColor assuming that it is a solid, you may have an incorrect appearance. You should use lightGrayColor in its place.

controlDarkShadowColor

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

public static NSColor controlDarkShadowColor()

Discussion

Controls are displayed as though they were lit from the upper left. Two dark borders, representing shadows, run along the bottom and right. controlDarkShadowColor returns the color of the outer, darker border. For general information about system colors, see “Accessing System Colors”.

See Also

controlHighlightColor

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

public static NSColor controlHighlightColor()

Discussion

Controls are displayed as though they were lit from the upper left. Two light borders, representing reflections from the light source, run along the top and left. controlHighlightColor returns the color of the inner, duller border. For general information about system colors, see “Accessing System Colors”.

See Also

controlLightHighlightColor

Returns the system color used for light highlights in controls.

public static NSColor controlLightHighlightColor()

Discussion

Controls are displayed as though they were lit from the upper left. Two light borders, representing reflections from the light source, run along the top and left. controlLightHighlightColor returns the color of the outer, brighter border. For general information about system colors, see “Accessing System Colors”.

See Also

controlShadowColor

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

public static NSColor controlShadowColor()

Discussion

Controls are displayed as though they were lit from the upper left. Two dark borders, representing shadows, run along the bottom and right. controlShadowColor returns the color of the inner, lighter border. For general information about system colors, see “Accessing System Colors”.

See Also

controlTextColor

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

public static NSColor controlTextColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

See Also

currentControlTint

Returns the current system control tint.

public static int currentControlTint()

Availability
See Also

cyanColor

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

public static NSColor cyanColor()

See Also

darkGrayColor

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

public static NSColor darkGrayColor()

See Also

disabledControlTextColor

Returns the system color used for text on disabled controls.

public static NSColor disabledControlTextColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

See Also

grayColor

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

public static NSColor grayColor()

See Also

greenColor

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

public static NSColor greenColor()

See Also

gridColor

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

public static NSColor gridColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

highlightColor

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

public static NSColor highlightColor()

Discussion

This method is invoked by the highlightWithLevel method. For general information about system colors, see “Accessing System Colors”.

See Also

ignoresAlpha

Returns true if the application doesn’t support alpha.

public static boolean ignoresAlpha()

Discussion

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 true 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 false.

See Also

keyboardFocusIndicatorColor

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

public static NSColor keyboardFocusIndicatorColor()

knobColor

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

public static NSColor knobColor()

Discussion

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 “Accessing System Colors”.

lightGrayColor

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

public static NSColor lightGrayColor()

See Also

magentaColor

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

public static NSColor magentaColor()

See Also

orangeColor

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

public static NSColor orangeColor()

purpleColor

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

public static NSColor purpleColor()

redColor

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

public static NSColor redColor()

See Also

scrollBarColor

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

public static NSColor scrollBarColor()

Discussion

. For general information about system colors, see “Accessing System Colors”.

secondarySelectedControlColor

Returns the system color used in nonkey views.

public static NSColor secondarySelectedControlColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

See Also

selectedControlColor

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

public static NSColor selectedControlColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

See Also

selectedControlTextColor

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

public static NSColor selectedControlTextColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

See Also

selectedKnobColor

Returns the system color used for the slider knob when it is selected—that is, dragged.

public static NSColor selectedKnobColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

See Also

selectedMenuItemColor

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

public static NSColor selectedMenuItemColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

See Also

selectedMenuItemTextColor

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

public static NSColor selectedMenuItemTextColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

See Also

selectedTextBackgroundColor

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

public static NSColor selectedTextBackgroundColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

See Also

selectedTextColor

Returns the system color used for selected text.

public static NSColor selectedTextColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

See Also

setIgnoresAlpha

public static void setIgnoresAlpha(boolean flag)

Discussion

If flag is true, 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 false and explicitly make colors opaque in cases where it matters to them. Note that calling this with a value of true overrides any value set with the NSColorPanel method setShowsAlpha.

See Also

shadowColor

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

public static NSColor shadowColor()

Discussion

This method is invoked by shadowWithLevel. For general information about system colors, see “Accessing System Colors”.

See Also

textBackgroundColor

Returns the system color used for the text background.

public static NSColor textBackgroundColor()

Discussion

When text is selected, its background color changes to the return value of selectedTextBackgroundColor. For general information about system colors, see “Accessing System Colors”.

See Also

textColor

Returns the system color used for text.

public static NSColor textColor()

Discussion

When text is selected, its background color changes to the return value of selectedTextColor. For general information about system colors, see “Accessing System Colors”.

See Also

whiteColor

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

public static NSColor whiteColor()

See Also

windowBackgroundColor

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

public static NSColor windowBackgroundColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

windowFrameColor

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

public static NSColor windowFrameColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

See Also

windowFrameTextColor

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

public static NSColor windowFrameTextColor()

Discussion

For general information about system colors, see “Accessing System Colors”.

See Also

yellowColor

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

public static NSColor yellowColor()

See Also

Instance Methods

alphaComponent

Returns the receiver’s alpha (opacity) component.

public float alphaComponent()

Discussion

Returns 1.0 (opaque) if the receiver has no alpha component.

blackComponent

Returns the receiver’s black component.

public float blackComponent()

Discussion

Throws an exception if the receiver isn’t a CMYK color.

blendedColorWithFractionOfColor

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

public NSColor blendedColorWithFractionOfColor(float fraction, NSColor color)

Discussion

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 null if the colors can’t be converted.

blueComponent

Returns the receiver’s blue component.

public float blueComponent()

Discussion

Throws an exception if the receiver isn’t an RGB color.

brightnessComponent

Returns the brightness component of the HSB color equivalent to the receiver.

public float brightnessComponent()

Discussion

Throws an exception if the receiver isn’t an RGB color.

catalogNameComponent

Returns the name of the catalog containing the receiver’s name.

public String catalogNameComponent()

Discussion

Throws an exception if the receiver’s color space isn’t NSGraphics.NamedColorSpace.

See Also

colorNameComponent

Returns the receiver’s name.

public String colorNameComponent()

Discussion

Throws an exception if the receiver’s color space isn’t NSGraphics.NamedColorSpace.

See Also

colorSpace

Returns an object representing the color space of the receiver.

public NSColorSpace colorSpace()

Discussion

The returned NSColorSpace object may represent a custom color space.

Availability

colorSpaceName

Returns the name of the receiver’s color space.

public String colorSpaceName()

Discussion

This method should be implemented in subclasses of NSColor.

See Also

colorUsingColorSpace

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

public NSColor colorUsingColorSpace(NSColorSpace space)

Discussion

In creating the new NSColor object, this method converts the receiver’s color to an equivalent one in the new color space. Although the new color might have different component values, it looks the same as the original. The method returns the same NSColor object as the receiver if its color space is the same as the one specified. Returns nil if conversion is not possible.

Availability

colorUsingColorSpaceName

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

public NSColor colorUsingColorSpaceName(String colorSpace)

Discussion

If colorSpace is null, the most appropriate color space is used.

Returns null if the specified conversion cannot be done.

See Also

colorUsingColorSpaceNameAndDevice

Creates and returns an NSColor whose color is the same as the receiver’s, except that the new NSColor is in the color space named colorSpace and is specific to the device described by deviceDescription.

public NSColor colorUsingColorSpaceNameAndDevice(String colorSpace, NSDictionary deviceDescription)

Discussion

Device descriptions can be obtained from windows, screens, and printers with the deviceDescription method. If colorSpace is null, the most appropriate color space is used.

If deviceDescription is null, the current device (as obtained from the currently lockFocus’ed view’s window or, if printing, the current printer) is used.

Returns null if the specified conversion cannot be done.

See Also

colorWithAlphaComponent

Creates and returns an NSColor that has the same color space and component values as the receiver, except its alpha component is alpha.

public NSColor colorWithAlphaComponent(float alpha)

Discussion

If the receiver’s color space doesn’t include an alpha component, the receiver is returned. A subclass with explicit opacity components should override this method to return a color with the specified alpha.

See Also

components

Returns the components of the receiver as an array of float values.

public float[] components()

Discussion

You can invoke this method on NSColor objects created from custom color spaces to get the individual floating point components, including alpha. Throws an exception if the receiver doesn’t have floating-point components. To find out how many components are in the array, send the receiver a numberOfComponents message.

Availability
See Also

cyanComponent

Returns the receiver’s cyan component.

public float cyanComponent()

Discussion

Throws an exception if the receiver isn’t a CMYK color.

drawSwatchInRect

Draws the current color in the rectangle rect.

public void drawSwatchInRect(NSRect rect)

Discussion

Subclasses adorn the rectangle in some manner to indicate the type of color. This method is invoked by color wells, swatches, and other user interface objects that need to display colors.

greenComponent

Returns the receiver’s green component.

public float greenComponent()

Discussion

Throws an exception if the receiver isn’t an RGB color.

highlightWithLevel

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

public NSColor highlightWithLevel(float highlightLevel)

Discussion

The highlight color’s contribution to the blend depends on highlightLevel, which should be a number from 0.0 through 1.0. (A highlightLevel below 0.0 is interpreted as 0.0 [the receiver]; a highlightLevel above 1.0 is interpreted as 1.0 [highlightLevel].)

Returns null if the colors can’t be converted. Invoke this method when you want to brighten the receiving NSColor for use in highlights.

See Also

hueComponent

Returns the hue component of the HSB color equivalent to the receiver.

public float hueComponent()

Discussion

Throws an exception if the receiver isn’t an RGB color.

localizedCatalogNameComponent

public String localizedCatalogNameComponent()

Discussion

Like catalogNameComponent, but returns a localized string. This string may be displayed in user interface items like color pickers.

See Also

localizedColorNameComponent

public String localizedColorNameComponent()

Discussion

Like colorNameComponent, but returns a localized string. This string may be displayed in user interface items like color pickers.

See Also

magentaComponent

Returns the receiver’s magenta component.

public float magentaComponent()

Discussion

Throws an exception if the receiver isn’t a CMYK color.

numberOfComponents

Returns the number of components in the receiver.

public int numberOfComponents()

Discussion

The floating-point components counted include alpha. Throws an exception if the receiver doesn’t have floating-point components.

Availability
See Also

patternImage

Returns the image that the receiver is using as a pattern.

public NSImage patternImage()

Discussion

Throws an exception if the receiver doesn’t have an image.

redComponent

Returns the receiver’s red component.

public float redComponent()

Discussion

Throws an exception if the receiver isn’t an RGB color.

saturationComponent

Returns the saturation component of the HSB color equivalent to the receiver.

public float saturationComponent()

Discussion

Throws an exception if the receiver isn’t an RGB color.

set

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

public void set()

Discussion

If the application is drawing to the screen rather than printing, this method also sets the current drawing context’s alpha value to the value returned by alphaComponent; if the color doesn’t know about alpha, it’s set to 1.0. This method should be implemented in subclasses.

setFill

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

public void setFill()

Discussion

If the application is drawing to the screen rather than printing, this method also sets the current drawing context’s alpha value to the value returned by alphaComponent; if the color doesn’t know about alpha, it’s set to 1.0.

Subclasses of NSColor should implement this method.

Availability
See Also

setStroke

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

public void setStroke()

Discussion

If the application is drawing to the screen rather than printing, this method also sets the current drawing context’s alpha value to the value returned by alphaComponent; if the color doesn’t know about alpha, it’s set to 1.0.

Subclasses of NSColor should implement this method.

Availability
See Also

shadowWithLevel

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

public NSColor shadowWithLevel(float shadowLevel)

Discussion

The shadow color’s contribution to the blend depends on shadowLevel, which should be a number from 0.0 through 1.0. (A shadowLevel below 0.0 is interpreted as 0.0 [the receiver]; a shadowLevel above 1.0 is interpreted as 1.0 [shadowLevel].)

Returns null if the colors can’t be converted. Invoke this method when you want to darken the receiving NSColor for use in shadows.

See Also

whiteComponent

Returns the receiver’s white component.

public float whiteComponent()

Discussion

Throws an exception if the receiver isn’t a grayscale color.

writeToPasteboard

Writes the receiver’s data to pasteBoard, unless pasteBoard doesn’t support color data (in which case the method does nothing).

public void writeToPasteboard(NSPasteboard pasteBoard)

See Also

yellowComponent

Returns the receiver’s yellow component.

public float yellowComponent()

Discussion

Throws an exception if the receiver isn’t a CMYK color.

Notifications

SystemColorsDidChangeNotification

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.



Next Page > Hide TOC

© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.