12.4 The JColorChooser Class

The JColorChooser class allows you to create a standard dialog with a color palette from which users can select a color.

12.4.1 Properties

In addition to the typical UI properties of Swing components, the color chooser has the properties listed in Table 12-6. The chooserPanels property contains an array of all the chooser panels currently associated with this color chooser. You can get and set the entire array at once or, more commonly, you can add and remove chooser panels using some of the methods described later. The color property contains the currently selected color in the chooser. (This property is just a convenient access point for the selectedColor property of the selectionModel.) The previewPanel property contains the JComponent subclass that previews your color choice. (You can see an example of the default preview panel in Figure 12-7.) The selectionModel property dictates which selection model the chooser uses. The dragEnabled property allows you to drag colors from the chooser to another part of your application, but no transferHandler (inherited from JPanel) is in place to support this feature yet. You would need to supply a handler to make this property meaningful.

Table 12-6. JColorChooser properties

Property	Data type	get	is	set	Default value
accessibleContext	AccessibleContext	·			JColorChooser.AccessibleJCol-orChooser( )
chooserPanelsb	AbstractColorChooser-Panel[]	·		·	null
color	Color	·		·	Color.white
dragEnabled1.4	boolean	·		·	false
previewPanelb	JComponent	·		·	null
selectionModelb	ColorSelectionModel	·		·	DefaultColorSelectionModel
UIb	ColorChooserUI	·		·	From L&F
UIClassIDo	String	·			"ColorChooserUI"
1.4since 1.4, bbound, ooverridden See also properties from the JComponent class (Table 3-6).

12.4.2 Events (Inherited from JComponent)

On its own, JColorChooser supports only PropertyChangeEvents, like all other Swing components. Using the static createDialog( ) method described below, you can attach your own ChangeListener to the color selection model for your chooser and react to changes in color anywhere in your program. You can even create a standalone chooser and add it to the container of your choice.

12.4.3 Constants

The JColorChooser class defines several constants for the property names used when firing PropertyChangeEvents, as shown in Table 12-7.

Table 12-7. JColorChooser property names for property change events

Constant	Type	Description
CHOOSER_PANELS_PROPERTY	String	The name of the chooserPanels property
PREVIEW_PANEL_PROPERTY	String	The name of the previewPanel property
SELECTION_MODEL_PROPERTY	String	The name of the selectionModel property

12.4.4 Constructors

public JColorChooser( )

public JColorChooser(Color initialColor)

public JColorChooser(ColorSelectionModel model)

These constructors create new JColorChooser panes. The first two versions use a DefaultColorSelectionModel. In the first two versions, where you do not specify an initial color, Color.white is used. In the last version, the color is extracted from the model.

12.4.5 Dialog Methods

public static JDialog createDialog(Component c, String title, boolean modal,

JColorChooser chooserPane, ActionListener okListener,

ActionListener cancelListener)

Create a (possibly modal) dialog window, with chooserPane as its main component. With this convenience method, you can add your own action listeners for the OK and Cancel buttons.

public static Color showDialog(Component c, String title, Color initialColor)

Create a modal dialog that waits for the user to press either the OK or Cancel button. If the user clicks on OK, the current color in the chooser is returned; otherwise, null is returned. No errors or exceptions are raised if the user cancels.

12.4.6 Chooser Methods

public void addChooserPanel(AbstractColorChooserPanel panel)

Add a new tab to the color chooser and place panel on that tab. An example using a custom chooser panel appears later in this chapter.

public AbstractColorChooserPanel removeChooserPanel(AbstractColorChooserPanel panel)

Remove a panel from the chooser. If panel is found on one of the tabs, it is removed and returned. If the panel is not found, null is returned.

public void setColor(int c)

public void setColor(int r, int g, int b)

You can use these methods as alternate ways of setting the color. They both affect the color property of JColorChooser. The first method expects a single RGB color (where the 1-byte alpha channel is ignored). The second method takes red, green, and blue values ranging from 0 to 255.

12.4.7 The AbstractColorChooserPanel Class

If you don't find the two chooser panels sufficient for your needs, you can write your own chooser panel and add it to the chooser along with the others. If you decide to do that, the AbstractColorChooserPanel (in the javax.swing.colorchooser package) is your starting point. This class has several properties you can fill in and a few abstract methods you must supply. Both of the panels in Figure 12-7 are based on this class. Later, we'll take a look at writing our own custom chooser panel.

12.4.7.1 Properties

The AbstractColorChooserPanel supports the properties shown in Table 12-8. The smallDisplayIcon and displayName properties should return values used in the tabs of the JColorChooser's tabbed pane. They can be null, but you should have at least one return a valid object, so that your tab contains some form of identification. The colorSelectionModel property accesses the colorSelectionModel of the enclosing chooser. The mnemonic and displayedMnemonicIndex properties are hints to the L&F to provide keyboard shortcuts to access this panel. The defaults simply mean that no mnemonic is available—the panel must be activated via the mouse or Tab/arrow key navigation.

Table 12-8. AbstractColorChooserPanel properties

Property	Data type	get	is	set	Default value
colorSelectionModel	ColorSelectionModel	·			DefaultColorSelection-Model( )
displayedMnemonicIndex1.4	int	·			-1
displayName*	String	·
largeDisplayIcon*	Icon	·
mnemonic1.4	int	·			0 (no mnemonic)
smallDisplayIcon*	Icon	·
1.4since 1.4 *The get call is abstract and must be supplied by the programmer, so no default value is available. See also properties from the JPanel class (Table 8-1).

12.4.7.2 Protected helper method

protected Color getColorFromModel( )

This protected method retrieves the current color from the ColorSelectionModel attached to this chooser panel.

12.4.7.3 Chooser panel methods

You'll need to override and use the following methods when developing your own panels. (You can see an example of a custom panel in the next section.)

protected abstract void buildChooser( )

Called to build your chooser panel when the color chooser is ready for it. It should be called only once.

public void installChooserPanel(JColorChooser enclosingChooser)

This method is called when you add your chooser panel to the color chooser's tabbed pane. It registers this panel as a listener for change events coming from the chooser's ColorSelectionModel. You don't normally need to override this method, but if you do, be sure to call the corresponding method from the superclass.

public void uninstallChooserPanel(JColorChooser enclosingChooser)

Called when the panel is removed from the chooser's tabbed pane. As you might expect, the panel is unregistered from the selection model. And, as with installChooserPanel( ), call the corresponding method from the superclass if you plan to override this. (You aren't required to call the superclass, but if you don't, you need to be sure that your install( ) and uninstall( ) methods cooperate.)

public abstract void updateChooser( )

This method should update your chooser panel to reflect the current color in the ColorSelectionModel. It is called automatically when the panel is added to the chooser, so you do not have to figure out the current color in the constructor or buildChooser( ) method.

12.4.8 The ColorChooserComponentFactory Class

The ColorChooserComponentFactory class provides a few small methods for creating components common to a color chooser panel. The default chooser panels you see in JColorChooser come from this class, but you are certainly not restricted to using these components.

12.4.8.1 Methods

public static AbstractColorChooserPanel[] getDefaultChooserPanels( )

Return an array containing instances of the package-private DefaultRGBChooser-Panel, DefaultSwatchChooserPanel, and DefaultHSBChooserPanel classes. These are the panels attached to the RGB, HSB, and Swatches tabs in Figure 12-7.

public static JComponent getPreviewPanel( )

Return an instance of the package-private DefaultPreviewPanel class. This is the preview panel used in the screenshots in Figure 12-7.