Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSColorPanel


Inherits from:
NSPanel : NSWindow : NSResponder : NSObject
Package:
com.apple.yellow.application


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, 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 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.


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


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.

NSColorPanel dynamically loads NSColorPickers from the following directories:




Constants


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



Method Types


Constructors
NSColorPanel
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
color


Constructors



NSColorPanel

public NSColorPanel()

Description forthcoming.

public NSColorPanel( NSRect aRect, int anInt, int anInt, boolean flag)

Description forthcoming.

public NSColorPanel( NSRect aRect, int anInt, int anInt, boolean flag, NSScreen aScreen)

Description forthcoming.


Static Methods



dragColor

public static boolean dragColor( NSColor color, NSEvent anEvent, NSView sourceView)

Drags color into a destination view from sourceView. This method is usually invoked by the mouseDown: method of sourceView. The dragging mechanism handles all subsequent events.

Because it is a static method, dragColor can be invoked whether or not the instance of NSColorPanel exists. Returns trueYES.



setPickerMask

public static void setPickerMask(int mask)

Accepts as a parameter one or more logically ORed color mode masks described in "Constants" .

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



setPickerMode

public static void setPickerMode(int mode)

Sets the color panel's initial picker to mode, which may be one of the symbolic constants described in "Constants" . 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



sharedColorPanel

public static NSColorPanel sharedColorPanel()

Returns the shared NSColorPanel, creating it if necessary.

sharedColorPanelExists

public static boolean sharedColorPanelExists()

Returns trueYES if the NSColorPanel has been created already.

See Also: sharedColorPanel




Instance Methods



accessoryView

public NSView accessoryView()

Returns the accessory view, or null if there is none.

See Also: setAccessoryView



attachColorList

public void attachColorList(NSColorList colorList)

Adds the specified list of NSColors to all the color pickers in the color panel that display color lists by invoking attachColorList on all color pickers in the application.

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



color

public NSColor color()

Returns the currently selected color in the NSColorPanel.

See Also: setColor



detachColorList

public void detachColorList(NSColorList colorList)

Removes the specified list of NSColors from all the color pickers in the color panel that display color lists by invoking detachColorList on all color pickers in the application.

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



isContinuous

public boolean isContinuous()

Returns whether the NSColorPanel continuously sends the action message to the target as the user manipulates the color picker.

See Also: setContinuous



mode

public int mode()

Returns the color picker mode of the NSColorPanel. The mode constants for the standard color pickers are listed in "Color Mask and Color Modes" .

See Also: setPickerMode, setMode



setAccessoryView

public void setAccessoryView(NSView aView)

Sets the accessory view displayed in the NSColorPanel to aView. The accessory view can be any custom view you want to display with NSColorPanel, such as a view offering color blends in a drawing program. The accessory view is displayed below the color picker and above the color swatches in the NSColorPanel. The NSColorPanel automatically resizes to accommodate the accessory view. Returns the previous accessory view, if there was one; otherwise, returns null.

See Also: accessoryView



setAction

public void setAction(NSSelector action)

Sets the action message to action. When you select a color in the color panel, or press the "Apply" button, NSColorPanel sends its action to its target, provided that neither the action nor the target is null. The action is null by default.

See Also: setTarget



setColor

public void setColor(NSColor color)

Sets the color of the NSColorPanel to color. This method posts a ColorPanelDidChangeNotification with the receiving object to the default notification center.

See Also: color



setContinuous

public void setContinuous(boolean flag)

Sets the NSColorPanel to send the action message to its target continuously as the color of the NSColorPanel is set by the user. Send this message with flag set to trueYES if, for example, you want to continuously update the color of the target.

See Also: isContinuous



setMode

public void setMode(int mode)

- (void)setMode:(int)mode

Sets the mode of the NSColorPanel if mode is one of the modes allowed by the color mask. The color mask is set when you first create the shared instance of NSColorPanel for an application. mode may be one of the symbolic constants described in "Constants" .

See Also: setPickerMode, mode



setShowsAlpha

public void setShowsAlpha(boolean flag)

Tells the NSColorPanel whether or not to show alpha values and an opacity slider.

See Also: alpha, showsAlpha



setTarget

public void setTarget(Object target)

Sets the target of the NSColorPanel to target. When you select a color in the color panel, or press the "Apply" button, NSColorPanel sends its action to its target, provided that neither the action nor the target is null. The target is null by default.

See Also: setAction, setContinuous



showsAlpha

public boolean showsAlpha()

Returns whether or not the NSColorPanel shows alpha values and an opacity slider.

See Also: alpha, setShowsAlpha




Methods Implemented By the Delegate


changeColor

public void changeColor(Object sender)

When the user presses the "Apply" button of an NSColorPanel, the NSColorPanel sends a changeColor action message to the first responder. You can override this method in any responder that needs to respond to a color change. sender is the color panel.


Notifications


ColorPanelColorChangedNotification

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.



Table of Contents