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.

• + (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.

• - (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.

+(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.