org.jdesktop.swingx.decorator
Class Highlighter

java.lang.Object
  org.jdesktop.swingx.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, 0)
  };

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

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.

Highlighters are mutable by default, that is all there properties can be changed dynamically. If so they fire changeEvents to registered ChangeListeners. They can be marked as immutable at instantiation time - if so, trying to mutate all properties will not have any effect, ChangeListeners are not registered and no events are fired.

This base class has properties background/foreground and corresponding selectionBackground/selectionForeground. It will apply those colors "absolutely", that is without actually computing any derived color. It's up to subclasses to implement color computation, if desired.

See Also:

ComponentAdapter, ListCellRenderer, TableCellRenderer, TreeCellRenderer

Nested Class Summary

static interface

Highlighter.UIHighlighter

Field Summary

protected ChangeEvent	changeEvent Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property.
protected boolean	immutable flag to indicate whether the Highlighter is mutable in every respect.
static Highlighter	ledgerBackground Deprecated. set the component's background color instead!
protected EventListenerList	listenerList The listeners waiting for model changes.
static Highlighter	notePadBackground Deprecated. set the component's background color instead!

Constructor Summary

Highlighter()
Default constructor for mutable Highlighter.

Highlighter(Color cellBackground, Color cellForeground)
Constructs a mutable Highlighter with the specified background and foreground colors, selectedBackground and selectedForeground to null.

Highlighter(Color cellBackground, Color cellForeground, boolean immutable)

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

Highlighter(Color cellBackground, Color cellForeground, Color selectedBackground, Color selectedForeground, boolean immutable)
Constructs a Highlighter with the specified background and foreground colors with mutability depending on given flag.

Method Summary

void	addChangeListener(ChangeListener l) Adds a ChangeListener if this is mutable.
protected void	applyBackground(Component renderer, ComponentAdapter adapter) Applies a suitable background for the renderer component within the specified adapter.
protected void	applyForeground(Component renderer, ComponentAdapter adapter) Applies a suitable foreground for the renderer component within the specified adapter.
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) Deprecated. this is no longer used by this implementation
protected Color	computeSelectedBackground(Component renderer, ComponentAdapter adapter) Computes a suitable selected background for the renderer component within the specified adapter and returns the computed color.
protected Color	computeSelectedForeground(Color seed) Deprecated. this method is longer called by this implementation
protected Color	computeSelectedForeground(Component renderer, ComponentAdapter adapter) Computes a suitable selected foreground for the renderer component within the specified adapter and returns the computed color.
protected Color	computeUnselectedBackground(Component renderer, ComponentAdapter adapter) Computes a suitable unselected background for the renderer component within the specified adapter and returns the computed color.
protected Color	computeUnselectedForeground(Component renderer, ComponentAdapter adapter) Computes a suitable unselected foreground for the renderer component within the specified adapter and returns the computed color.
protected Component	doHighlight(Component renderer, ComponentAdapter adapter) This is the bottleneck decorate method that all highlighters must invoke to decorate the cell renderer.
protected void	fireStateChanged() Runs each ChangeListener's stateChanged method.
Color	getBackground() Returns the background color of this Highlighter.
ChangeListener[]	getChangeListeners() Returns an array of all the change listeners registered on 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.
boolean	isImmutable() Returns immutable flag: if true, none of the setXX methods have any effects, there are no listeners added and no change events fired.
void	removeChangeListener(ChangeListener l) Removes a ChangeListener if this is mutable.
void	setBackground(Color color) Sets the background color of this Highlighter and notifies registered ChangeListeners if this is mutable.
void	setForeground(Color color) Sets the foreground color of this Highlighter and notifies registered ChangeListeners if this is mutable.
void	setSelectedBackground(Color color) Sets the selected background color of this Highlighter and notifies registered ChangeListeners if this is mutable.
void	setSelectedForeground(Color color) Sets the selected foreground color of this Highlighter and notifies registered ChangeListeners if this is mutable.

Methods inherited from class java.lang.Object

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

Field Detail

changeEvent

protected transient ChangeEvent changeEvent

Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property. The source of events generated here is always "this".

listenerList

protected EventListenerList listenerList

The listeners waiting for model changes.

immutable

protected final boolean immutable

flag to indicate whether the Highlighter is mutable in every respect.

ledgerBackground

public static final Highlighter ledgerBackground

Deprecated. set the component's background color instead!

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

Deprecated. set the component's background color instead!

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.

Constructor Detail

Highlighter

public Highlighter()

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

Highlighter

public Highlighter(Color cellBackground,
                   Color cellForeground)

Constructs a mutable Highlighter with the specified background and foreground colors, selectedBackground and selectedForeground to null.

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

Highlighter

public Highlighter(Color cellBackground,
                   Color cellForeground,
                   boolean immutable)

Highlighter

public Highlighter(Color cellBackground,
                   Color cellForeground,
                   Color selectedBackground,
                   Color selectedForeground)

Constructs a mutable 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

Highlighter

public Highlighter(Color cellBackground,
                   Color cellForeground,
                   Color selectedBackground,
                   Color selectedForeground,
                   boolean immutable)

Constructs a Highlighter with the specified background and foreground colors with mutability depending on given flag.

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, to decorate the corresponding attributes of the specified component within the given adapter.

Subclasses which want to decorate additional properties must override this and additionally call custom applyXX methods.

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)

Applies a suitable background for the renderer component within the specified adapter.

This implementation calls computeBackground and applies the computed color to the component if the returned value is != null. Otherwise it does nothing.

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)

Applies a suitable foreground for the renderer component within the specified adapter.

This implementation calls computeForeground and applies the computed color to the component if the returned value is != null. Otherwise it does nothing.

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.

In this implementation the returned color depends on isSelected: it will return computSelected/-UnselectedBackground, respectively.

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

computeUnselectedBackground

protected Color computeUnselectedBackground(Component renderer,
                                            ComponentAdapter adapter)

Computes a suitable unselected background for the renderer component within the specified adapter and returns the computed color. This implementation returns getBackground().

Parameters:

renderer -

adapter -

Returns:

unselected background color

computeSelectedBackground

protected Color computeSelectedBackground(Component renderer,
                                          ComponentAdapter adapter)

Computes a suitable selected background for the renderer component within the specified adapter and returns the computed color. This implementation returns getSelectedBackground().

Parameters:

renderer -

adapter -

Returns:

selected background color

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. In this implementation the returned color depends on isSelected: it will return computSelected/-UnselectedForeground, respectively.

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

computeUnselectedForeground

protected Color computeUnselectedForeground(Component renderer,
                                            ComponentAdapter adapter)

Computes a suitable unselected foreground for the renderer component within the specified adapter and returns the computed color. This implementation returns getForeground().

Parameters:

renderer -

adapter -

Returns:

unselected foreground color

computeSelectedForeground

protected Color computeSelectedForeground(Component renderer,
                                          ComponentAdapter adapter)

Computes a suitable selected foreground for the renderer component within the specified adapter and returns the computed color. This implementation returns getSelectedForeground().

Parameters:

renderer -

adapter -

Returns:

selected foreground color

computeSelectedBackground

protected Color computeSelectedBackground(Color seed)

Deprecated. this is no longer used by this implementation

Computes the selected background color. This implementation simply returns the selectedBackground property.

Parameters:

seed - initial background color; must cope with null!

Returns:

the background color for a selected cell

computeSelectedForeground

protected Color computeSelectedForeground(Color seed)

Deprecated. this method is longer called by this implementation

Computes the selected foreground color. This implementation simply returns the selectedBackground property.

Parameters:

seed - initial foreground color; must cope with null!

Returns:

the foreground color for a selected cell

isImmutable

public boolean isImmutable()

Returns immutable flag: if true, none of the setXX methods have any effects, there are no listeners added and no change events fired.

Returns:

true if none of the setXX methods have any effect

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 and notifies registered ChangeListeners if this is mutable. Does nothing if immutable.

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 and notifies registered ChangeListeners if this is mutable. Does nothing if immutable.

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 and notifies registered ChangeListeners if this is mutable. Does nothing if immutable.

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 and notifies registered ChangeListeners if this is mutable. Does nothing if immutable.

Parameters:

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

addChangeListener

public void addChangeListener(ChangeListener l)

Adds a ChangeListener if this is mutable. ChangeListeners are notified after changes of any attribute. Does nothing if immutable.

Parameters:

l - the ChangeListener to add

See Also:

removeChangeListener(javax.swing.event.ChangeListener)

removeChangeListener

public void removeChangeListener(ChangeListener l)

Removes a ChangeListener if this is mutable. Does nothis if immutable.

Parameters:

l - the ChangeListener to remove

See Also:

addChangeListener(javax.swing.event.ChangeListener)

getChangeListeners

public ChangeListener[] getChangeListeners()

Returns an array of all the change listeners registered on this Highlighter.

Returns:

all of this model's ChangeListeners or an empty array if no change listeners are currently registered

Since:

1.4

See Also:

addChangeListener(javax.swing.event.ChangeListener), removeChangeListener(javax.swing.event.ChangeListener)

fireStateChanged

protected void fireStateChanged()

Runs each ChangeListener's stateChanged method.