org.jdesktop.swing.decorator
Class Highlighter

java.lang.Object
  org.jdesktop.swing.decorator.Highlighter

Direct Known Subclasses:

AlternateRowHighlighter, ConditionalHighlighter, HierarchicalColumnHighlighter

public class Highlighter

extends Object

Highlighter is a lightweight mechanism to modify the behavior and attributes of cell renderers such as ListCellRenderer, TableCellRenderer, and TreeCellRenderer in a simple layered fashion. While cell renderers are split along component lines, highlighters provide a common interface for decorating cell renderers. Highlighter achieves this by vectoring access to all component-specific state and functionality through a ComponentAdapter object.

The primary purpose of Highlighter is to decorate a cell renderer in controlled ways, such as by applying a different color or font to it. For example, AlternateRowHighlighter highlights cell renderers with alternating background colors. In data visualization components that support multiple columns with potentially different types of data, this highlighter imparts the same background color consistently across all columns of the target component regardless of the actual cell renderer registered for any specific column. Thus, the Highlighter mechanism is orthogonal to the cell rendering mechanism.

To use Highlighter you must first set up a HighlighterPipeline using an array of Highlighter objects, and then call setHighlighters() on a data visualization component, passing in the highligher pipeline. If the array of highlighters is not null and is not empty, the highlighters are applied to the selected renderer for each cell in the order they appear in the array. When it is time to render a cell, the cell renderer is primed as usual, after which, the highlight method of the first highlighter in the HighlighterPipeline is invoked. The prepared renderer, and a suitable ComponentAdapter object is passed to the highlight method. The highlighter is expected to modify the renderer in controlled ways, and return the modified renderer (or a substitute) that is passed to the next highlighter, if any, in the pipeline. The renderer returned by the highlight method of the last highlighter in the pipeline is ultimately used to render the cell.

The Highlighter mechanism enables multiple degrees of freedom. In addition to specifying the actual cell renderer class, now you can also specify the number, order, and class of highlighter objects. Using highlighters is really simple, as shown by the following example:

    Highlighter[]	highlighters = new Highlighter[] {
        new AlternateRowHighlighter(Color.white, new Color(0xF0, 0xF0, 0xE0), null)),
        new PatternHighlighter(null, Color.red, "s.*", 0)};

    HighlighterPipeline	highlighterPipeline = new HighlighterPipeline(highlighters);
    JTable table = new JTable();
    table.setHighlighters(highlighters);
 

The above example allocates an array of Highlighter and populates it with a new AlternateRowHighlighter and PatternHighlighter. The first one in this example highlights all cells in odd rows with a white background, and all cells in even rows with a silver background, but it does not specify a foreground color explicitly. The second highlighter does not specify a background color explicitly, but sets the foreground color to red if certain conditions are met (see PatternHighlighter for more details). In this example, if the cells in the first column of any row start with the letter 's', then all cells in that row are highlighted with a red foreground. Also, as mentioned earlier, the highlighters are applied in the order they appear in the list.

See Also:

ComponentAdapter, ListCellRenderer, TableCellRenderer, TreeCellRenderer

Field Summary

protected Color	background
protected Color	foreground
static Highlighter	ledgerBackground Predefined Highlighter that highlights the background of each cell with a pastel green "ledger" background color, and is most effective when the ComponentAdapter.target component has horizontal gridlines in Color.cyan.darker() color.
static Highlighter	notePadBackground Predefined Highlighter that decorates the background of each cell with a pastel yellow "notepad" background color, and is most effective when the ComponentAdapter.target component has horizontal gridlines in Color.cyan.darker() color.
protected int	order
protected Color	selectedBackground
protected Color	selectedForeground

Constructor Summary

Highlighter()
Default constructor.

Highlighter(Color cellBackground, Color cellForeground)
Constructs a Highlighter with the specified background and foreground colors.

Method Summary

protected void	applyBackground(Component renderer, ComponentAdapter adapter) Computes a suitable background for the renderer component within the specified adapter by calling computeBackground and applies the computed color to the component.
protected void	applyFont(Component renderer, ComponentAdapter adapter) Empty method.
protected void	applyForeground(Component renderer, ComponentAdapter adapter) Computes a suitable foreground for the renderer component within the specified adapter by calling computeForeground and applies the computed color to the component.
protected Color	computeBackground(Component renderer, ComponentAdapter adapter) Computes a suitable background for the renderer component within the specified adapter and returns the computed color.
protected Color	computeForeground(Component renderer, ComponentAdapter adapter) Computes a suitable foreground for the renderer component within the specified adapter and returns the computed color.
protected Color	computeSelectedBackground(Color seed) Computes the selected background color.
protected Color	computeSelectedForeground(Color seed) Computes the selected foreground color.
protected Component	doHighlight(Component renderer, ComponentAdapter adapter) This is the bottleneck decorate method that all highlighters must invoke to decorate the cell renderer.
Color	getBackground() Returns the background color of this Highlighter.
Color	getForeground() Returns the foreground color of this Highlighter.
Color	getSelectedBackground() Returns the selected background color of this Highlighter.
Color	getSelectedForeground() Returns the selected foreground color of this Highlighter.
Component	highlight(Component renderer, ComponentAdapter adapter) Decorates the specified cell renderer component for the given component data adapter using highlighters that were previously set for the component.
void	setBackground(Color color) Sets the background color of this Highlighter.
void	setForeground(Color color) Sets the foreground color of this Highlighter.
void	setSelectedBackground(Color color) Sets the selected background color of this Highlighter.
void	setSelectedForeground(Color color) Sets the selected foreground color of this Highlighter.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

order

protected int order

ledgerBackground

public static final Highlighter ledgerBackground

Predefined Highlighter that highlights the background of each cell with a pastel green "ledger" background color, and is most effective when the ComponentAdapter.target component has horizontal gridlines in Color.cyan.darker() color.

notePadBackground

public static final Highlighter notePadBackground

Predefined Highlighter that decorates the background of each cell with a pastel yellow "notepad" background color, and is most effective when the ComponentAdapter.target component has horizontal gridlines in Color.cyan.darker() color.

background

protected Color background

foreground

protected Color foreground

selectedBackground

protected Color selectedBackground

selectedForeground

protected Color selectedForeground

Constructor Detail

Highlighter

public Highlighter()

Default constructor. Initializes background, foreground, selectedBackground, and selectedForeground to null.

Highlighter

public Highlighter(Color cellBackground,
                   Color cellForeground)

Constructs a Highlighter with the specified background and foreground colors.

Parameters:

cellBackground - background color for the renderer, or null, to compute a suitable background

cellForeground - foreground color for the renderer, or null, to compute a suitable foreground

Method Detail

highlight

public Component highlight(Component renderer,
                           ComponentAdapter adapter)

Decorates the specified cell renderer component for the given component data adapter using highlighters that were previously set for the component. This method unconditionally invokes doHighlight with the same arguments as were passed in.

Parameters:

renderer - the cell renderer component that is to be decorated

adapter - the ComponentAdapter for this decorate operation

Returns:

the decorated cell renderer component

doHighlight

protected Component doHighlight(Component renderer,
                                ComponentAdapter adapter)

This is the bottleneck decorate method that all highlighters must invoke to decorate the cell renderer. This method invokes applyBackground, applyForeground, applyFont and so on, to decorate the corresponding attributes of the specified component within the given adapter.

Parameters:

renderer - the cell renderer component that is to be decorated

adapter - the ComponentAdapter for this decorate operation

Returns:

the decorated cell renderer component

applyBackground

protected void applyBackground(Component renderer,
                               ComponentAdapter adapter)

Computes a suitable background for the renderer component within the specified adapter by calling computeBackground and applies the computed color to the component. If the computed color is null, it leaves the background unchanged; Otherwise it sets the component's background to the computed color.

Parameters:

renderer - the cell renderer component that is to be decorated

adapter - the ComponentAdapter for this decorate operation

applyForeground

protected void applyForeground(Component renderer,
                               ComponentAdapter adapter)

Computes a suitable foreground for the renderer component within the specified adapter by calling computeForeground and applies the computed color to the component. If the computed color is null, it leaves the foreground unchanged; Otherwise it sets the component's foreground to the computed color.

Parameters:

renderer - the cell renderer component that is to be decorated

adapter - the ComponentAdapter for this decorate operation

applyFont

protected void applyFont(Component renderer,
                         ComponentAdapter adapter)

Empty method. Override it to change the font of the renderer component.

Parameters:

renderer - the cell renderer component that is to be decorated

adapter - the ComponentAdapter for this decorate operation

computeBackground

protected Color computeBackground(Component renderer,
                                  ComponentAdapter adapter)

Computes a suitable background for the renderer component within the specified adapter and returns the computed color. The computed color depends on two factors: (i) whether the background color for this Highlighter is null or not, and (ii) whether the cell identified by the specified adapter isSelected or not.

If the background color for this Highlighter is not null, this method starts with an initial value that is equal to that background color, and proceeds to check the selected state of the cell. Otherwise, it starts with the background color of the component whose cell is being rendererd (not the background color of the renderer component that was passed in), and proceeds to check the selected state of the cell.

If the cell identified by the specified adapter is selected, this method returns the value computed by computeSelectedBackground when passed the initial background color computed earlier. Otherwise, it simply returns the initial background color computed earlier.

Parameters:

renderer - the cell renderer component that is to be decorated

adapter - the ComponentAdapter for this decorate operation

Returns:

a suitable background color for the specified component and adapter

computeForeground

protected Color computeForeground(Component renderer,
                                  ComponentAdapter adapter)

Computes a suitable foreground for the renderer component within the specified adapter and returns the computed color. The computed color depends on two factors: (i) whether the foreground color for this Highlighter is null or not, and (ii) whether the cell identified by the specified adapter isSelected or not.

If the foreground color for this Highlighter is not null, this method starts with an initial value that is equal to that foreground color, and proceeds to check the selected state of the cell. Otherwise, it starts with the foreground color of the component whose cell is being rendererd (not the foreground color of the renderer component that was passed in), and proceeds to check the selected state of the cell.

If the cell identified by the specified adapter is selected, this method returns the value computed by computeSelectedBackground when passed the initial foreground color computed earlier. Otherwise, it simply returns the initial foreground color computed earlier.

Parameters:

renderer - the cell renderer component that is to be decorated

adapter - the ComponentAdapter for this decorate operation

Returns:

a suitable foreground color for the specified component and adapter

computeSelectedBackground

protected Color computeSelectedBackground(Color seed)

Computes the selected background color. If the selected background color of this Highlighter is not null, this method returns that color. Otherwise, it returns a Color.darker() version of the specified seed color.

Parameters:

seed - initial background color; must not be null

Returns:

the background color for a selected cell

computeSelectedForeground

protected Color computeSelectedForeground(Color seed)

Computes the selected foreground color. If the selected foreground color of this Highlighter is not null, this method returns that color. Otherwise, it returns Color.white, ignoring the specified seed color.

Parameters:

seed - initial foreground color

Returns:

the foreground color for a selected cell

getBackground

public Color getBackground()

Returns the background color of this Highlighter.

Returns:

the background color of this Highlighter, or null, if no background color has been set

setBackground

public void setBackground(Color color)

Sets the background color of this Highlighter.

Parameters:

color - the background color of this Highlighter, or null, to clear any existing background color

getForeground

public Color getForeground()

Returns the foreground color of this Highlighter.

Returns:

the foreground color of this Highlighter, or null, if no foreground color has been set

setForeground

public void setForeground(Color color)

Sets the foreground color of this Highlighter.

Parameters:

color - the foreground color of this Highlighter, or null, to clear any existing foreground color

getSelectedBackground

public Color getSelectedBackground()

Returns the selected background color of this Highlighter.

Returns:

the selected background color of this Highlighter, or null, if no selected background color has been set

setSelectedBackground

public void setSelectedBackground(Color color)

Sets the selected background color of this Highlighter.

Parameters:

color - the selected background color of this Highlighter, or null, to clear any existing selected background color

getSelectedForeground

public Color getSelectedForeground()

Returns the selected foreground color of this Highlighter.

Returns:

the selected foreground color of this Highlighter, or null, if no selected foreground color has been set

setSelectedForeground

public void setSelectedForeground(Color color)

Sets the selected foreground color of this Highlighter.

Parameters:

color - the selected foreground color of this Highlighter, or null, to clear any existing selected foreground color