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

Table of Contents

NSColorPickingDefault


Package:
com.apple.yellow.application

Interface Description


The NSColorPickingDefault protocol, together with the NSColorPickingCustom protocol, provides an interface for adding color pickers-custom user interfaces for color selection-to an application's NSColorPanel. The NSColorPickingDefault protocol provides basic behavior for a color picker. The NSColorPickingCustom protocol provides implementation-specific behavior.

The NSColorPicker class implements the NSColorPickingDefault protocol. The simplest way to implement your own color picker is to create a subclass of NSColorPicker, implementing the NSColorPickingCustom protocol for that subclass. However, it's possible to create a subclass of another class, such as NSView, and use it as a base upon which to add the methods of both NSColorPickingDefault and NSColorPickingCustom.


Color Picker Bundles


A class that implements the NSColorPickingDefault and NSColorPickingCustom protocols needs to be compiled and linked in an application's object file. However, your application need not explicitly create an instance of this class. Instead, your application's file package should include a directory named ColorPickers; within this directory you should place a directory MyPickerClass.bundle for each custom color picker your application implements. This bundle should contain all resources required for your color picker: nib files, TIFF files, and so on.

NSColorPanel will allocate and initialize an instance of each class for which a bundle is found in the ColorPickers directory. The class name is assumed to be the bundle directory name minus the .bundle extension.


Color Picker Buttons


NSColorPanel lets the user select a color picker from an NSMatrix of NSButtonCells. This protocol includes methods for providing and manipulating the image that gets displayed on the button.


Color Mask and Color Modes


The color mask determines which color mode is 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. The predefined color mask constants are:


ModeColor Mask Constant
Grayscale-AlphaColorPanelGrayModeMask
Red-Green-BlueColorPanelRGBModeMask
Cyan-Yellow-Magenta-BlackColorPanelCMYKModeMask
Hue-Saturation-BrightnessColorPanelHSBModeMask
Custom paletteColorPanelCustomPaletteModeMask
Custom color listColorPanelColorListModeMask
Color wheelColorPanelWheelModeMask
All of the aboveColorPanelAllModesMask

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:


ModeColor Mode Constant
Grayscale-AlphaGrayModeColorPanel
Red-Green-BlueRGBModeColorPanel
Cyan-Yellow-Magenta-BlackCMYKModeColorPanel
Hue-Saturation-BrightnessHSBModeColorPanel
Custom paletteCustomPaletteModeColorPanel
Custom color listColorListModeColorPanel
Color wheelWheelModeColorPanel

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 NSPopUpLists for loading and saving files. Finally, color wheel mode provides a simplified control for selecting colors.



Method Types


Setting the Mode
setMode
Using Color Lists
attachColorList
detachColorList
Adding Button Images
insertNewButtonImage
provideNewButtonImage
Showing Opacity Controls
alphaControlAddedOrRemoved
Responding to a Resized View
viewSizeChanged


Instance Methods



alphaControlAddedOrRemoved

public abstract void alphaControlAddedOrRemoved(Object sender)

Sent by the color panel when the opacity controls have been hidden or displayed. Invoked automatically when the NSColorPanel's opacity slider is added or removed; you never invoke this method directly.

If the color picker has its own opacity controls, it should hide or display them, depending on whether the sender's showsAlpha method returns false or true.



attachColorList

public abstract void attachColorList(NSColorList colorList)

Tells the color picker to attach the given colorList, if it isn't already displaying the list. You never invoke this method; it's invoked automatically by the NSColorPanel when its attachColorList method is invoked. Because NSColorPanel's list mode manages NSColorLists, this method need only be implemented by a custom color picker that manages NSColorLists itself.

See Also: detachColorList



detachColorList

public abstract void detachColorList(NSColorList colorList)

Tells the color picker to detach the given colorList, unless the receiver isn't displaying the list. You never invoke this method; it's invoked automatically by the NSColorPanel when its detachColorList method is invoked. Because NSColorPanel's list mode manages NSColorLists, this method need only be implemented by a custom color picker that manages NSColorLists itself.

See Also: attachColorList



insertNewButtonImage

public abstract void insertNewButtonImage( NSImage newButtonImage, NSButtonCell buttonCell)

Sets newButtonImage as buttonCell's image. buttonCell is the NSButtonCell object that lets the user choose the picker from the color panel-the color picker's representation in the NSColorPanel's picker NSMatrix. This method should perform application-specific manipulation of the image before it's inserted and displayed by the button cell.

See Also: provideNewButtonImage



provideNewButtonImage

public abstract NSImage provideNewButtonImage()

Returns the image for the mode button the user uses to select this picker in the color panel, that is, the color picker's representation in the NSColorPanel's picker NSMatrix. (This is the same image the color panel uses as an argument when sending the insertNewButtonImage message.)

setMode

public abstract void setMode(int mode)

Sets the color picker's mode. This method is invoked by NSColorPanel's setMode method to ensure the color picker reflects the current mode. For example, invoke this method during color picker initialization to ensure that all color pickers are restored to the mode the user left them in the last time an NSColorPanel was used.

Most color pickers have only one mode, and thus don't need to do any work in this method. An example of a color picker that uses this method is the slider picker, which can choose from one of several submodes depending on the value of mode. The available modes are described in "Color Mask and Color Modes" .



viewSizeChanged

public abstract void viewSizeChanged(Object sender)

Tells the color picker when the NSColorPanel's view size changes in a way that might affect the color picker. sender is the NSColorPanel that contains the color picker. Use this method to perform special preparation when resizing the color picker's view. Because this method is invoked only as appropriate, it's better to implement this method than to override the method superviewSizeChanged for the NSView in which the color picker's user interface is contained.

See Also: provideNewView (NSColorPickingCustom protocol)




Table of Contents