- Inherits from:
- NSPanel : NSWindow : NSResponder : NSObject
- Conforms to:
- NSCoding
- (NSResponder)
- NSObject (NSObject)
Declared in:
- AppKit/NSColorPanel.h
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, or to drag a color from the color panel into an application view.
When you press the color panel's "Apply" button, NSColorPanel
sends a changeColor: message
to the first responder. It also sends its action message (set by setAction:) to its
target object (set by setTarget:),
provided that neither the action nor the target is nil
.
NSColorPanel also sends its action to its target whenever you select
a color in the color panel.
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 put NSColorPanel in any application created with Interface Builder by adding the "Colors..." item from the Menu palette to the application's menu.
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 |
Custom palette | NSColorPanelCustomPaletteModeMask |
Custom color list | 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 |
Custom palette | NSCustomPaletteModeColorPanel |
Custom color list | 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 an NSImage file (TIFF or EPS) into the NSColorPanel, then select colors from the image. In custom color list mode, the user can create and load lists of named colors. The two custom modes provide NSPopUpButtons 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.
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.
NSColorPanel dynamically loads NSColorPickers from the following directories:
~/Library/ColorPickers/
/Local/Library/ColorPickers/
/System/Library/ColorPickers/
These constants specify which of the color modes the NSColorPanel can use. For more information, see "Color Mask and Color Modes" .
Constant | Description |
NSColorPanelGrayModeMask |
Grayscale-Alpha |
NSColorPanelRGBModeMask |
Red-Green-Blue |
NSColorPanelCMYKModeMask |
Cyan-Yellow-Magenta-Black |
NSColorPanelHSBModeMask |
Hue-Saturation-Brightness |
NSColorPanelCustomPaletteModeMask |
Custom palette |
NSColorPanelColorListModeMask |
Custom color list |
NSColorPanelWheelModeMask |
Color wheel |
NSColorPanelAllModesMask |
All of the above |
These constants specify the active color mode used when an application's instance of NSColorPanel is masked for more than one color mode. For more information, see "Color Mask and Color Modes" .
Color Mode Constant | Description |
NSGrayModeColorPanel |
Grayscale-Alpha |
NSRGBModeColorPanel |
Red-Green-Blue |
NSCMYKModeColorPanel |
Cyan-Yellow-Magenta-Black |
NSHSBModeColorPanel |
Hue-Saturation-Brightness |
NSCustomPaletteModeColorPanel |
Custom palette |
NSColorListModeColorPanel |
Custom color list |
NSWheelModeColorPanel |
Color wheel |
- Creating the NSColorPanel
- + sharedColorPanel
- + sharedColorPanelExists
- Setting color picker modes
- + setPickerMask:
- + setPickerMode:
- Setting the NSColorPanel
- - accessoryView
- - isContinuous
- - mode
- - setAccessoryView:
- - setAction:
- - setContinuous:
- - setMode:
- - setShowsAlpha:
- - setTarget:
- - showsAlpha
- Attaching a color list
- - attachColorList:
- - detachColorList:
- Setting color
- + dragColor:withEvent:fromView:
- - setColor:
- Getting color information
- - alpha
- - color
+ (BOOL)dragColor:(NSColor
*)color
withEvent:(NSEvent *)anEvent
fromView:(NSView *)sourceView
Because it is a class method, dragColor:withEvent:fromView: can
be invoked whether or not the instance of NSColorPanel exists. Returns trueYES
.
+ (void)setPickerMask:(int)mask
AppKit/NSColorPanel.h
).This determines which color selection modes will be available in an application's NSColorPanel. This method only has an effect before NSColorPanel is instantiated.
If you create a class that implements the color picking protocols (NSColorPickingDefault and NSColorPickingCustom), you may want to give it a unique mask-one different from those defined for the standard color pickers. To display your color picker, your application will need to logically OR that unique mask with the standard color mask constants when invoking this method.
See Also: + setPickerMode:
+ (void)setPickerMode:(int)mode
AppKit/NSColorPanel.h
).
The mode determines which picker will initially be visible. This
method may be called at any time, whether or not an application's NSColorPanel
has been instantiated. See Also: + setPickerMask:, - setMode:
+ (NSColorPanel *)sharedColorPanel
+ (BOOL)sharedColorPanelExists
trueYES
if
the NSColorPanel has been created already.See Also: + sharedColorPanel
- (NSView *)accessoryView
nil
if there is none.See Also: - setAccessoryView:
- (float)alpha
See Also: - setShowsAlpha:, - showsAlpha
- (void)attachColorList:(NSColorList
*)colorList
An application should use this method to add an NSColorList saved with a document in its file package or in a directory other than NSColorList's standard search directories.
See Also: - detachColorList:
- (NSColor *)color
See Also: - setColor:
- (void)detachColorList:(NSColorList
*)colorList
Your application should use this method to remove an NSColorList saved with a document in its file package or in a directory other than NSColorList's standard search directories.
See Also: - attachColorList:
- (BOOL)isContinuous
See Also: - setContinuous:
- (int)mode
See Also: + setPickerMode:, - setMode:
- (void)setAccessoryView:(NSView
*)aView
nil
.See Also: - accessoryView
- (void)setAction:(SEL)action
nil
.
The action is nil
by
default.See Also: - setTarget:
- (void)setColor:(NSColor
*)color
See Also: - color
- (void)setContinuous:(BOOL)flag
trueYES
if, for example, you want to
continuously update the color of the target.See Also: - isContinuous
public void setMode(int mode)
- (void)setMode:(int)mode
AppKit/NSColorPanel.h
).See Also: + setPickerMode:, - mode
- (void)setShowsAlpha:(BOOL)flag
See Also: - alpha, - showsAlpha
- (void)setTarget:(id)target
nil
.
The target is nil
by
default.See Also: - setAction:, - setContinuous:
- (BOOL)showsAlpha
See Also: - alpha, - setShowsAlpha:
- (void)changeColor:(id)sender
Posted when the NSColorPanel's color is set, as when setColor: is invoked. This notification contains a notification object but no userInfo dictionary. The notification object is the notifying NSColorPanel.