Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSColorPanel 

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 

+ (NSColorPanel *)sharedColorPanel	Creates if necessary and returns the shared NSColorPanel.

+ (BOOL)sharedColorPanelExists	Returns YES if the NSColorPanel has been created already.

Setting the NSColorPanel 

+ (void)setPickerMask:(int)mask	Sets the mask that determines which color selection modes are available in the color panel.

+ (void)setPickerMode:(int)mode	Sets the color picker mode.

- (NSView *)accessoryView	Returns the accessory view, or nil if there is none.

- (BOOL)isContinuous	Returns YES if the NSColorPanel continuously sends the action message to the target.

- (int)mode	Returns the mode of the NSColorPanel.

- (void)setAccessoryView:(NSView *)aView	Sets the accessory view to aView.

- (void)setAction:(SEL)aSelector	Sets the action message sent to the target.

- (void)setContinuous:(BOOL)flag	Sets the NSColorPanel to continuously send the action message to the target.

- (void)setMode:(int)mode	Sets the mode of the NSColorPanel.

- (void)setShowsAlpha:(BOOL)flag	Sets the NSColorPanel to show alpha values.

- (void)setTarget:(id)anObject	Sets the target of the NSColorPanel.

- (BOOL)showsAlpha	Returns YES if the NSColorPanel shows alpha values.

Attaching a Color List

- (void)attachColorList:(NSColorList *)aColorList	
	Adds the specified list of NSColors to all the color pickers in the color panel that display color lists.

- (void)detachColorList:(NSColorList *)aColorList	
	Removes the specified list of NSColors from all the color pickers in the color panel that display color lists.

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.