Return to the Alphabetic Index
Return to the Class Browser
Return to the Picture Browser
Copyright (c) 1994 by NeXT Computer, Inc. All Rights Reserved.


Inherits From: NSPanel : NSWindow : NSResponder : NSObject

Conforms To: NSCoding (NSResponder) NSObject (NSObject)

Declared In: AppKit/NSColorPanel.h

Class Description

NSColorPanel provides a standard user interface for selecting color in an application. It provides a number of standard color selection modes, and, with the NSColorPickingDefault and NSColorPickingCustom protocols, allows an application to add its own color selection modes. It allows the user to save swatches containing frequently used colors. Once set, these swatches are displayed by NSColorPanel in any application where it is used, giving the user color consistency between applications. NSColorPanel enables users to capture a color anywhere on the screen for use in the active application, and allows dragging colors from itself into views in an application. NSColorPanel's action message is sent to the target object when the user changes the current color.

An application has only one instance of NSColorPanel, the shared instance. Invoking the sharedColorPanel: method returns the shared instance of NSColorPanel, instantiating it if necessary. You can also initialize an NSColorPanel for your application by invoking NSApplication's orderFrontColorPanel method.

You can put NSColorPanel in any application created with Interface Builder by adding the Colors... item from the Menu palette to the application's menu.

Color Mask and Color Modes

The color mask determines which of the color modes are enabled for NSColorPanel. This mask is set before you initialize a new instance of NSColorPanel. NSColorPanelAllModesMask represents the logical OR of the other color mask constants: it causes the NSColorPanel to display all standard color pickers. When initializing a new instance of NSColorPanel, you can logically OR any combination of color mask constants to restrict the available color modes.

Mode Color Mask Constant

Grayscale-Alpha NSColorPanelGrayModeMask

Red-Green-Blue NSColorPanelRGBModeMask

Cyan-Yellow-Magenta-Black NSColorPanelCMYKModeMask

Hue-Saturation-Brightness NSColorPanelHSBModeMask

TIFF image NSColorPanelCustomPaletteModeMask

Custom color lists NSColorPanelColorListModeMask

Color wheel NSColorPanelWheelModeMask

All of the above NSColorPanelAllModesMask

The NSColorPanel's color mode mask is set using the class method setPickerMask:. The mask must be set before creating an application's instance of NSColorPanel.

When an application's instance of NSColorPanel is masked for more than one color mode, your program can set its active mode by invoking the setMode: method with a color mode constant as its argument; the user can set the mode by clicking buttons on the panel. Here are the standard color modes and mode constants:

Mode Color Mode Constant

Grayscale-Alpha NSGrayModeColorPanel

Red-Green-Blue NSRGBModeColorPanel

Cyan-Yellow-Magenta-Black NSCMYKModeColorPanel

Hue-Saturation-Brightness NSHSBModeColorPanel

TIFF image NSCustomPaletteModeColorPanel

Color lists NSColorListModeColorPanel

Color wheel NSWheelModeColorPanel

In grayscale-alpha, red-green-blue, cyan-magenta-yellow-black, and hue-saturation-brightness modes, the user adjusts colors by manipulating sliders. In the custom palette mode, the user can load a TIFF file into the NSColorPanel, then select colors from the TIFF image. In custom color list mode, the user can create and load lists of named colors. The two custom modes provide NSPopUpLists for loading and saving files. Finally, color wheel mode provides a simplified control for selecting colors. If a color panel has been used, it uses whatever mode it was in last as the default mode when NSColorPanelAllModesMask is used to initialize the NSColorPanel. Otherwise, it uses color wheel mode.

Associated Classes and Protocols

The NSColorList class provides an API for managing custom color lists. The NSColorPanel methods attachColorList: and detachColorList: let your application add and remove custom lists from the NSColorPanel's user interface.

The protocols NSColorPickingDefault and NSColorPickingCustom provide an API for adding custom color selection to the user interface. The NSColorPicker class implements the NSColorPickingDefault protocol; you can subclass NSColorPicker and implement the NSColorPickingCustom protocol in your subclass to create your own user interface for color selection.

See also: NSColorList, NSColorPickingDefault, NSColorPicker, NSColorPickingDefault protocol, NSColorPickingCustom protocol, NSColorWell

Creating the NSColorPanel

Setting the NSColorPanel

Attaching a Color List

Setting Color

+(BOOL)dragColor:(NSColor **)aColor Drags aColor into a destination view from sourceView.

withEvent:(NSEvent *)anEvent

fromView:(NSView *)sourceView

- (float)alpha Returns the NSColorPanel's current alpha value, or 1.0 (opaque) if the panel has no opacity slider.

- (NSColor *)color Returns the currently displayed color.

- (void)setColor:(NSColor *)aColor Sets the color to be displayed. This method posts the NSColorPanelChangedNotification notification with the receiving object to the default notification center.