Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.


Inherits From: Panel : Window : Responder : Object
Declared In: appkit/NXColorPanel.h

Class Description

NXColorPanel provides a standard user interface for selecting color in an application.  It provides a number of standard color selection modes, and, with the NXColorPickingDefault and NXColorPickingCustom protocols, allows an application to add its own color selection modes.  It allows the user to set swatches containing frequently used colors.  Once set, these swatches are displayed by NXColorPanel in any application where it is used, giving the user color consistency between applications. NXColorPanel enables users to capture a color anywhere on the screen for use in the active application, and provides API for dragging colors between views in an application.  NXColorPanel's action message is sent to the target object when the user changes the current color.

An application has only one instance of NXColorPanel, the shared instance.  Invoking the sharedInstance: method returns the shared instance of NXColorPanel, instantiating it if necessary. You can also initialize an NXColorPanel for your application by invoking Application's orderFrontColorPanel method.

You can put NXColorPanel 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 NXColorPanel.  This mask is set before you initialize a new instance of NXColorPanel.  NX_ALLMODESMASK represents the logical OR of the other color mask constants: it causes the NXColorPanel to display all standard color pickers.  When initializing a new instance of NXColorPanel, you can logically OR any combination of color mask constants to restrict the available color modes.

Mode Color Mask Constant
Cyan-Yellow-Magenta-Black NX_CMYKMODEMASK
Hue-Saturation-Brightness NX_HSBMODEMASK
All of the above NX_ALLMODESMASK

The NXColorPanel's color mode mask is set using the class method setPickerMask:.  The mask must be set before creating an application's instance of NXColorPanel.

When an application's instance of NXColorPanel is masked for more than one color mode, your program can set its 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 NX_GRAYMODE
Red-Green-Blue NX_RGBMODE
Cyan-Yellow-Magenta-Black NX_CMYKMODE
Hue-Saturation-Brightness NX_HSBMODE
Color wheel NX_BEGINMODE

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 a TIFF file into the NXColorPanel, then select colors from the TIFF image.  In custom color list mode, the user can create and load lists of named colors.  The two custom modes provide PopUpLists for loading and saving files.  Finally, color wheel mode provides a simplified control for selecting colors; by default, it's the initial mode when the NX_ALLMODESMASK constant is used to initialize the NXColorPanel.

Associated Classes and Protocols

The NXColorList class provides an API for managing custom color lists.  The NXColorPanel methods attachColorList: and detachColorList: let your application add and remove custom lists from the NXColorPanel's user interface.

The protocols NXColorPickingDefault and NXColorPickingCustom provide an API for adding custom color selection to the user interface.  The NXColorPicker class implements the NXColorPickingDefault protocol; you can subclass NXColorPicker and implement the NXColorPickingCustom protocol in your subclass to create your own user interface for color selection.

See also:  NXColorList, NXColorPicker, NXColorPickingDefault protocol, NXColorPickingCustom protocol, NXColorWell

Instance Variables

None declared in this class.

Method Types

Creating a New NXColorPanel + sharedInstance:
Setting Color setColor:
Target and Action setAction:
Mode setMode:
Alpha alpha
Picker settings + setPickerMode:
+ setPickerMask:
Accessory View setAccessoryView:
Color list management attachColorList:
Color dragging + dragColor:withEvent:fromView:
Archiving read:

Class Methods


Generates an error message.  This method cannot be used to create NXColorPanel instances.  Use the sharedInstance: class method instead.

See also:  + sharedInstance:


Generates an error message.  This method cannot be used to create NXColorPanel instances.  Use the sharedInstance: class method instead.

See also:  + sharedInstance:

+ (BOOL)dragColor:(NXColor)color
withEvent:(NXEvent *)theEvent

Drags colors between views in an application.  This method is usually invoked by the mouseDown: method of controlView.  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 NXColorPanel exists.  Returns YES.

+ (void)setPickerMask:(int)mask

Accepts as a parameter one or more logically OR'd color mode masks (defined in the header file appkit/NXColorPanel.h). This determines which color selection modes will be available in an application's NXColorPanel.  This method only has an effect before NXColorPanel is instantiated.

If you create a class that implements the color picking protocols (NXColorPickingDefault and NXColorPickingCustom), 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:  NXColorPicker class, NXColorPickingDefault protocol, NXColorPickingCustom protocol

+ (void)setPickerMode:(int)mode

Sets the color panel's initial picker mode.  The mode determines which picker will initially be visible.  This method may be called at any time, whether or not an application's NXColorPanel has been instantiated.

See also:  setMode:, setMode: (NXColorPicker)

+ sharedInstance:(BOOL)create

Returns the shared instance of NXColorPanel.  If create is YES, this method creates, if necessary, and returns the NXColorPanel.  If create is NO and the shared instance exists, this method returns it; if no instance of NXColorPanel exists, returns nil.

See also:  orderFrontColorPanel (Application)

Instance Methods


Returns the NXColorPanel's accessory View.

See also:  setAccessoryView:


Notifies color pickers (objects that conform to the NXColorPickingDefault and NXColorPickingCustom protocols) when a new NXColorList is added to the NXColorPanel.  Your application should use this method to add an NXColorList saved with a document in its file package or in a directory other than NXColorList's standard search directories.  This method invokes attachColorList: on all color pickers in the application.

See also:  detachColorList:, NXColorList, NXColorPicker, NXColorPickingDefault protocol, NXColorPickingCustom protocol


Returns the current alpha level of the NXColorPanel based on its opacity slider.  If the NXColorPanel has no opacity slider, returns 1.0 (opaque).

See also:  doesShowAlpha, setShowAlpha:


Returns the color selected in the NXColorPanel.

See also:  setColor


Notifies color pickers (objects that conform to the NXColorPickingDefault and NXColorPickingCustom protocols)  when an NXColorList is removed from the NXColorPanel.  Your application should use this method to remove an NXColorList saved with a document in its file package or in a directory other than NXColorList's standard search directories.  This method invokes detachColorList: on all color pickers in the application.

See also:  attachColorList:, NXColorList, NXColorPicker, NXColorPickingDefault protocol, NXColorPickingCustom protocol


Returns YES if the alpha (opacity) slider is currently displayed by the NXColorPanel; NO if not.  The opacity slider is independent of the currently selected color picker.

See also:  setShowAlpha


Returns whether or not the NXColorPanel's color is being set continuously as the user manipulates the color picker.

See also:  setContinuous:


Returns the current color picker mode for the NXColorPanel.  The mode constants for the standard color pickers are listed in the class description.

read:(NXTypedStream *)theStream

Reads the NXColorPanel from the typed stream theStream.  Returns self.


Sets the accessory View displayed in the NXColorPanel to aView.  The accessory View can be any custom View that you want to display with NXColorPanel, 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 NXColorPanel.  The NXColorPanel automatically resizes to accommodate the accessory View.  Returns the previous accessory view, if there was one; otherwise, returns nil.

See also:  accessoryView


Sets the action of the NXColorPanel to aSelector.  Returns self.

See also:  setTarget:


Sets the color setting of the NXColorPanel to color and redraws the panel.  Returns self.

See also:  color


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

See also:  isContinuous


Sets the mode of the NXColorPanel 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 NXColorPanel for an application.  mode may be one of these symbolic constants, declared in the header file appkit/NXColorPanel.h:


If you create a color picker--a class that implements the NXColorPickingDefault and NXColorPickingCustom protocols--it should define a unique mode value that differs from those for the standard color pickers.

Color modes and masks are described in the class description.

Returns self.

See also:  mode


If flag is YES, sets the NXColorPanel to show alpha.  Returns self.

See also:  doesShowAlpha


Sets the target of the NXColorPanel to anObject.  The NXColorPanel's target is the object to which the action message is sent when the user selects a color.  Returns self.

See also:  setAction:, setContinuous:


Updates the current custom color lists.  This method sends each color picker an updateColorList: message with a nil argument.  Color pickers are objects conforming to the NXColorPickingDefault and NXColorPickingCustom protocols.