Inherits from: NSPanel : NSWindow : NSResponder : NSObject
Package: com.apple.yellow.application
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 "Set" 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 null
.
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. ColorPanelAllModesMask
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 | ColorPanelGrayModeMask |
Red-Green-Blue | ColorPanelRGBModeMask |
Cyan-Yellow-Magenta-Black | ColorPanelCMYKModeMask |
Hue-Saturation-Brightness | ColorPanelHSBModeMask |
Custom palette | ColorPanelCustomPaletteModeMask |
Custom color list | ColorPanelColorListModeMask |
Color wheel | ColorPanelWheelModeMask |
All of the above | ColorPanelAllModesMask |
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 | GrayModeColorPanel |
Red-Green-Blue | RGBModeColorPanel |
Cyan-Yellow-Magenta-Black | CMYKModeColorPanel |
Hue-Saturation-Brightness | HSBModeColorPanel |
Custom palette | CustomPaletteModeColorPanel |
Custom color list | ColorListModeColorPanel |
Color wheel | WheelModeColorPanel |
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 ColorPanelAllModesMask
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:
These constants specify which of the color modes the NSColorPanel
can use. For more information, see Color Mask and Color Modes.
Constant | Description |
ColorPanelGrayModeMask |
Grayscale-Alpha |
ColorPanelRGBModeMask |
Red-Green-Blue |
ColorPanelCMYKModeMask |
Cyan-Yellow-Magenta-Black |
ColorPanelHSBModeMask |
Hue-Saturation-Brightness |
ColorPanelCustomPaletteModeMask |
Custom palette |
ColorPanelColorListModeMask |
Custom color list |
ColorPanelWheelModeMask |
Color wheel |
ColorPanelAllModesMask |
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 |
GrayModeColorPanel |
Grayscale-Alpha |
RGBModeColorPanel |
Red-Green-Blue |
CMYKModeColorPanel |
Cyan-Yellow-Magenta-Black |
HSBModeColorPanel |
Hue-Saturation-Brightness |
CustomPaletteModeColorPanel |
Custom palette |
ColorListModeColorPanel |
Custom color list |
WheelModeColorPanel |
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
- setColor
- Getting color information
- alpha
- color
public NSColorPanel(NSRect aRect, int anInt, int anInt, boolean flag)
public NSColorPanel(NSRect aRect, int anInt, int anInt, boolean flag, NSScreen aScreen)
public static boolean dragColor(NSColor color, NSEvent anEvent, NSView sourceView)
Because it is a static method, dragColor can be
invoked whether or not the instance of NSColorPanel exists. Returns trueYES
.
public static void setPickerMask(int mask)
ColorPanelGrayModeMask
ColorPanelRGBModeMask
ColorPanelCMYKModeMask
ColorPanelHSBModeMask
ColorPanelCustomPaletteModeMask
ColorPanelColorListModeMask
ColorPanelWheelModeMask
ColorPanelAllModesMask
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
public static void setPickerMode(int mode)
See Also: setPickerMask, setMode
public static NSColorPanel sharedColorPanel()
public static boolean sharedColorPanelExists()
trueYES
if
the NSColorPanel has been created already.See Also: sharedColorPanel
public NSView accessoryView()
null
if there is none.See Also: setAccessoryView
- (float)alpha
See Also: setShowsAlpha, showsAlpha
public 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
public NSColor color()
See Also: setColor
public 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
public boolean isContinuous()
See Also: setContinuous
public int mode()
See Also: setPickerMode, setMode
public void setAccessoryView(NSView aView)
null
.See Also: accessoryView
public void setAction(NSSelector action)
null
.
The action is null
by
default.See Also: setTarget
public void setColor(NSColor color)
See Also: color
public void setContinuous(boolean 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
GrayModeColorPanel
RGBModeColorPanel
CMYKModeColorPanel
HSBModeColorPanel
CustomPaletteModeColorPanel
ColorListModeColorPanel
WheelModeColorPanel
See Also: setPickerMode, mode
public void setShowsAlpha(boolean flag)
See Also: alpha, showsAlpha
public void setTarget(Object target)
null
.
The target is null
by default.See Also: setAction, setContinuous
public boolean showsAlpha()
See Also: alpha, setShowsAlpha
public void changeColor(Object 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.