PATH  Documentation > Mac OS X > Application Kit Reference: Objective-C

Table of Contents

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


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


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



Method Types


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


Class Methods



dragColor:withEvent:fromView:

+ (BOOL)dragColor:(NSColor *)color withEvent:(NSEvent *)anEvent fromView:(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 class method, dragColor:withEvent:fromView: can be invoked whether or not the instance of NSColorPanel exists. Returns trueYES.



setPickerMask:

+ (void)setPickerMask:(int)mask

Accepts as a parameter one or more logically ORed color mode masks described in "Constants" and (defined in the header file 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:



setPickerMode:

+ (void)setPickerMode:(int)mode

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



sharedColorPanel

+ (NSColorPanel *)sharedColorPanel

Returns the shared NSColorPanel, creating it if necessary.

sharedColorPanelExists

+ (BOOL)sharedColorPanelExists

Returns trueYES if the NSColorPanel has been created already.

See Also: + sharedColorPanel




Instance Methods



accessoryView

- (NSView *)accessoryView

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

See Also: - setAccessoryView:



alpha

- (float)alpha

Returns the NSColorPanel's current alpha value based on its opacity slider. Returns 1.0 (opaque) if the panel has no opacity slider.

See Also: - setShowsAlpha:, - showsAlpha



attachColorList:

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

- (NSColor *)color

Returns the currently selected color in the NSColorPanel.

See Also: - setColor:



detachColorList:

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

- (BOOL)isContinuous

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

See Also: - setContinuous:



mode

- (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:

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

See Also: - accessoryView



setAction:

- (void)setAction:(SEL)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 nil. The action is nil by default.

See Also: - setTarget:



setColor:

- (void)setColor:(NSColor *)color

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

See Also: - color



setContinuous:

- (void)setContinuous:(BOOL)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" (and declared in the header file AppKit/NSColorPanel.h).

See Also: + setPickerMode:, - mode



setShowsAlpha:

- (void)setShowsAlpha:(BOOL)flag

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

See Also: - alpha, - showsAlpha



setTarget:

- (void)setTarget:(id)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 nil. The target is nil by default.

See Also: - setAction:, - setContinuous:



showsAlpha

- (BOOL)showsAlpha

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

See Also: - alpha, - setShowsAlpha:




Methods Implemented By the Delegate


changeColor:

- (void)changeColor:(id)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 id of the color panel.


Notifications


NSColorPanelColorChangedNotification

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