NSColorPanel Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSColorPanel.h
Related sample code

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

Configuring the Color Panel

Managing Color Lists

Setting Color Picker Modes

Setting Color

Getting Color Information

Responding to a Color Change

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 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 Picker 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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
Declared In
NSColorPanel.h

color

Returns the currently selected color in the receiver.

- (NSColor *)color
Return Value

The currently selected color.

Availability
  • Available in OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
Declared In
NSColorPanel.h

mode

Returns the color picker mode of the receiver.

Return Value

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

Availability
  • Available in OS X v10.0 and later.
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 OS X v10.0 and later.
Related Sample Code
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.

Availability
  • Available in OS X v10.0 and later.
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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
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 Panel Modes.” The color mask is set when you first create the shared instance of NSColorPanel for an application.

Availability
  • Available in OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 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 OS X v10.0 and later.

Declared in NSColorPanel.h.

NSColorPanelRGBModeMask

Red-green-blue.

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSColorPanelCMYKModeMask

Cyan-yellow-magenta-black.

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSColorPanelHSBModeMask

Hue-saturation-brightness.

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSColorPanelCustomPaletteModeMask

Custom palette.

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSColorPanelColorListModeMask

Custom color list.

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSColorPanelWheelModeMask

Color wheel.

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSColorPanelCrayonModeMask

Crayons.

Declared in NSColorPanel.h.

Available in OS X v10.2 and later.

NSColorPanelAllModesMask

All of the above.

Available in 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 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 OS X version 10.5 and later.

Declared in NSColorPanel.h.

NSGrayModeColorPanel

Grayscale-alpha

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSRGBModeColorPanel

Red-green-blue

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSCMYKModeColorPanel

Cyan-yellow-magenta-black

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSHSBModeColorPanel

Hue-saturation-brightness

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSCustomPaletteModeColorPanel

Custom palette

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSColorListModeColorPanel

Custom color list

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSWheelModeColorPanel

Color wheel

Available in OS X v10.0 and later.

Declared in NSColorPanel.h.

NSCrayonModeColorPanel

Crayons.

Declared in NSColorPanel.h.

Available in OS X v10.2 and later.

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
Declared In
NSColorPanel.h