---

NSColorPanel Class Reference

Overview

The NSColorPanel class 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.

Tasks

Obtaining the Shared Color-Panel Object

• + sharedColorPanel
• + sharedColorPanelExists

Configuring the Color Panel

• – accessoryView
• – isContinuous
• – mode
• – setAccessoryView:
• – setAction:
• – setContinuous:
• – setMode:
• – setShowsAlpha:
• – setTarget:
• – showsAlpha

Managing Color Lists

• – attachColorList:
• – detachColorList:

Setting Color Picker Modes

• + setPickerMask:
• + setPickerMode:

Setting Color

• + dragColor:withEvent:fromView:
• – setColor:

Getting Color Information

• – alpha
• – color

Responding to a Color Change

• – changeColor:  delegate method

Class Methods

dragColor:withEvent:fromView:

Drags a color into a destination view from the specified source view.

+ (BOOL)dragColor:(NSColor *)color withEvent:(NSEvent *)anEvent fromView:(NSView *)sourceView

Parameters

color

The color to drag.

anEvent

The drag event.

sourceView

The view from which the color was dragged.

Return Value

YES

Discussion

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.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColorPanel.h

setPickerMask:

Determines which color selection modes are available in an application’s NSColorPanel.

+ (void)setPickerMask:(NSUInteger)mask

Parameters

mask

One or more logically ORed color mode masks described in Color Panel Mode Masks.

Discussion

This method has an effect only before an NSColorPanel object 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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + setPickerMode:

Declared In

NSColorPanel.h

setPickerMode:

Specifies the color panel’s initial picker.

+ (void)setPickerMode:(NSColorPanelMode)mode

Parameters

mode

A constant specifying which color picker mode is initially visible. This is one of the symbolic constants described in Color Panel Modes.

Discussion

This method may be called at any time, whether or not an application’s NSColorPanel has been instantiated.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + setPickerMask:
• – setMode:

Declared In

NSColorPanel.h

sharedColorPanel

Returns the shared NSColorPanel instance, creating it if necessary.

+ (NSColorPanel *)sharedColorPanel

Return Value

The shared NSColorPanel instance.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColorPanel.h

sharedColorPanelExists

Returns a Boolean value indicating whether the NSColorPanel has been created already.

+ (BOOL)sharedColorPanelExists

Return Value

YES if the NSColorPanel has been created already; otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + sharedColorPanel

Declared In

NSColorPanel.h

Instance Methods

accessoryView

Returns the accessory view.

- (NSView *)accessoryView

Return Value

The accessory view or nil if there is none.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAccessoryView:

Declared In

NSColorPanel.h

alpha

Returns the receiver’s current alpha value based on its opacity slider.

- (CGFloat)alpha

Return Value

The alpha value of the NSColorPanel. This is 1.0 (opaque) if the panel has no opacity slider.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setShowsAlpha:
• – showsAlpha

Declared In

NSColorPanel.h

attachColorList:

Adds the list of NSColor objects specified to all the color pickers in the receiver that display color lists by invoking attachColorList: on all color pickers in the application.

- (void)attachColorList:(NSColorList *)colorList

Parameters

colorList

The list of colors to add to the color pickers in the receiver.

Discussion

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – detachColorList:

Declared In

NSColorPanel.h

color

Returns the currently selected color in the receiver.

- (NSColor *)color

Return Value

The currently selected color.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setColor:

Declared In

NSColorPanel.h

detachColorList:

Removes the list of colors from all the color pickers in the receiver that display color lists by invoking detachColorList: on all color pickers in the application.

- (void)detachColorList:(NSColorList *)colorList

Parameters

colorList

The list of NSColor objects to remove from the color pickers in the color panel.

Discussion

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – attachColorList:

Declared In

NSColorPanel.h

isContinuous

Returns a Boolean value indicating whether the receiver continuously sends the action message to the target.

- (BOOL)isContinuous

Return Value

YES if the receiver continuously sends the action message to the target as the user manipulates the color picker; otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setContinuous:

Declared In

NSColorPanel.h

mode

Returns the color picker mode of the receiver.

- (NSColorPanelMode)mode

Return Value

A constant indicating the current color picker mode. See Color Panel Modes.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + setPickerMode:
• – setMode:

Declared In

NSColorPanel.h

setAccessoryView:

Sets the accessory view displayed in the receiver.

- (void)setAccessoryView:(NSView *)aView

Parameters

aView

The accessory view displayed in the receiver. 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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – accessoryView

Declared In

NSColorPanel.h

setAction:

Sets the color panel's action message.

- (void)setAction:(SEL)action

Return Value

The action message. When you select a color in the color panel NSColorPanel sends its action to its target, provided that neither the action nor the target is nil. The action is NULL by default.

Discussion

See Action Messages for additional information on action messages.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setTarget:

Declared In

NSColorPanel.h

setColor:

Sets the color of the receiver.

- (void)setColor:(NSColor *)color

Parameters

color

The color of the NSColorPanel.

Discussion

This method posts an NSColorPanelColorDidChangeNotification with the receiver to the default notification center.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – color

Declared In

NSColorPanel.h

setContinuous:

Sets the receiver to send the action message to its target continuously as the user sets the color.

- (void)setContinuous:(BOOL)flag

Parameters

flag

YES to have the receiver send its action message to its target continuously as the color of the NSColorPanel is set by the user; otherwise NO. Set this to YES if, for example, you want to continuously update the color of the target.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isContinuous

Declared In

NSColorPanel.h

setMode:

Sets the mode of the receiver the mode is one of the modes allowed by the color mask.

- (void)setMode:(NSColorPanelMode)mode

Parameters

mode

A constant specifying the mode of the color panel. These constants are described in Color Picker Modes. The color mask is set when you first create the shared instance of NSColorPanel for an application.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + setPickerMode:
• – mode

Declared In

NSColorPanel.h

setShowsAlpha:

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

- (void)setShowsAlpha:(BOOL)flag

Parameters

flag

YES to have the color panel show alpha values and an opacity slider; otherwise NO.

Discussion

Note that calling the NSColor method setIgnoresAlpha: with a value of YES overrides any value set with this method.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – alpha
• – showsAlpha

Declared In

NSColorPanel.h

setTarget:

Sets the target of the receiver.

- (void)setTarget:(id)target

Parameters

target

The target of the receiver. When you select a color in the color panel NSColorPanel sends its action to its target, provided that neither the action nor the target is nil. The target is nil by default.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAction:
• – setContinuous:

Declared In

NSColorPanel.h

showsAlpha

Returns a Boolean value indicating whether or not the receiver shows alpha values and an opacity slider.

- (BOOL)showsAlpha

Return Value

YES if the color picker shows alpha values and an opacity slider; otherwise NO.

Discussion

Note that calling the NSColor method setIgnoresAlpha: with a value of YES overrides any value set with setShowsAlpha:.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – alpha
• – setShowsAlpha:

Declared In

NSColorPanel.h

Delegate Methods

changeColor:

Sent to the first responder when the user selects a color in an NSColorPanel object.

- (void)changeColor:(id)sender

Parameters

sender

The NSColorPanel sending the message.

Discussion

When the user selects a color in an NSColorPanel object, the panel 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.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColorPanel.h

Constants

Color Picker Mode Masks

Used to specify in the setPickerMask: class method which of the color modes the NSColorPanel can use.

enum {
   NSColorPanelGrayModeMask            = 0x00000001,
   NSColorPanelRGBModeMask             = 0x00000002,
   NSColorPanelCMYKModeMask            = 0x00000004,
   NSColorPanelHSBModeMask             = 0x00000008,
   NSColorPanelCustomPaletteModeMask   = 0x00000010,
   NSColorPanelColorListModeMask       = 0x00000020,
   NSColorPanelWheelModeMask           = 0x00000040,
   NSColorPanelCrayonModeMask          = 0x00000080,
   NSColorPanelAllModesMask            = 0x0000ffff
};
   

Constants

NSColorPanelGrayModeMask

Grayscale-alpha.

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSColorPanelRGBModeMask

Red-green-blue.

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSColorPanelCMYKModeMask

Cyan-yellow-magenta-black.

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSColorPanelHSBModeMask

Hue-saturation-brightness.

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSColorPanelCustomPaletteModeMask

Custom palette.

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSColorPanelColorListModeMask

Custom color list.

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSColorPanelWheelModeMask

Color wheel.

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSColorPanelCrayonModeMask

Crayons.

Available in Mac OS X v10.2 and later.

Declared in NSColorPanel.h

NSColorPanelAllModesMask

All of the above.

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

Discussion

For more information, see “Choosing the Color Pickers in a Color Panel”.

Declared In

NSColorPanel.h

NSColorPanelMode

A type defined for the enum constants specifying color panel modes.

typedef NSInteger NSColorPanelMode;

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSColorPanel.h

Color Panel Modes

Specify the active color mode used when an application’s instance of NSColorPanel is masked for more than one color mode.

enum {
   NSNoModeColorPanel             = -1,
   NSGrayModeColorPanel            = 0,
   NSRGBModeColorPanel             = 1,
   NSCMYKModeColorPanel            = 2,
   NSHSBModeColorPanel             = 3,
   NSCustomPaletteModeColorPanel   = 4,
   NSColorListModeColorPanel       = 5,
   NSWheelModeColorPanel           = 6,
   NSCrayonModeColorPanel          = 7
};

Constants

NSNoModeColorPanel

Indicates no color panel mode.

Available in Mac OS X version 10.5 and later.

Declared in NSColorPanel.h

NSGrayModeColorPanel

Grayscale-alpha

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSRGBModeColorPanel

Red-green-blue

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSCMYKModeColorPanel

Cyan-yellow-magenta-black

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSHSBModeColorPanel

Hue-saturation-brightness

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSCustomPaletteModeColorPanel

Custom palette

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSColorListModeColorPanel

Custom color list

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSWheelModeColorPanel

Color wheel

Available in Mac OS X v10.0 and later.

Declared in NSColorPanel.h

NSCrayonModeColorPanel

Crayons.

Available in Mac OS X v10.2 and later.

Declared in NSColorPanel.h

Discussion

These enum constants are specified or returned in the instance methods mode and setMode:, and in the setPickerMode:class method. For more information, see “Choosing the Color Pickers in a Color Panel”.

Declared In

NSColorPanel.h

Notifications

NSColorPanelColorDidChangeNotification

Posted when the color of the NSColorPanel is set, as when setColor: is invoked.

The notification object is the notifying NSColorPanel. This notification does not contain a userInfo dictionary.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColorPanel.h

---