org.jdesktop.swingx.decorator
Class Highlighter

java.lang.Object
  extended by org.jdesktop.swingx.decorator.Highlighter
Direct Known Subclasses:
AlternateRowHighlighter, ConditionalHighlighter, HierarchicalColumnHighlighter

public class Highlighter
extends java.lang.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.

Author:
Ramesh Gupta
See Also:
ComponentAdapter, ListCellRenderer, TableCellRenderer, TreeCellRenderer

Nested Class Summary
static interface Highlighter.UIHighlighter
           
 
Field Summary
protected  javax.swing.event.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
          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.
protected  javax.swing.event.EventListenerList listenerList
          The listeners waiting for model changes.
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.
 
Constructor Summary
Highlighter()
          Default constructor for mutable Highlighter.
Highlighter(java.awt.Color cellBackground, java.awt.Color cellForeground)
          Constructs a mutable Highlighter with the specified background and foreground colors, selectedBackground and selectedForeground to null.
Highlighter(java.awt.Color cellBackground, java.awt.Color cellForeground, boolean immutable)
           
Highlighter(java.awt.Color cellBackground, java.awt.Color cellForeground, java.awt.Color selectedBackground, java.awt.Color selectedForeground)
          Constructs a mutable Highlighter with the specified background and foreground colors.
Highlighter(java.awt.Color cellBackground, java.awt.Color cellForeground, java.awt.Color selectedBackground, java.awt.Color selectedForeground, boolean immutable)
          Constructs a Highlighter with the specified background and foreground colors with mutability depending on given flag.
 
Method Summary
 void addChangeListener(javax.swing.event.ChangeListener l)
          Adds a ChangeListener.
protected  void applyBackground(java.awt.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(java.awt.Component renderer, ComponentAdapter adapter)
          Empty method.
protected  void applyForeground(java.awt.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  java.awt.Color computeBackground(java.awt.Component renderer, ComponentAdapter adapter)
          Computes a suitable background for the renderer component within the specified adapter and returns the computed color.
protected  java.awt.Color computeForeground(java.awt.Component renderer, ComponentAdapter adapter)
          Computes a suitable foreground for the renderer component within the specified adapter and returns the computed color.
protected  java.awt.Color computeSelectedBackground(java.awt.Color seed)
          Computes the selected background color.
protected  java.awt.Color computeSelectedForeground(java.awt.Color seed)
          Computes the selected foreground color.
protected  java.awt.Component doHighlight(java.awt.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.
 java.awt.Color getBackground()
          Returns the background color of this Highlighter.
 javax.swing.event.ChangeListener[] getChangeListeners()
          Returns an array of all the change listeners registered on this DefaultBoundedRangeModel.
 java.awt.Color getForeground()
          Returns the foreground color of this Highlighter.
 java.awt.Color getSelectedBackground()
          Returns the selected background color of this Highlighter.
 java.awt.Color getSelectedForeground()
          Returns the selected foreground color of this Highlighter.
 java.awt.Component highlight(java.awt.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(javax.swing.event.ChangeListener l)
          Removes a ChangeListener.
 void setBackground(java.awt.Color color)
          Sets the background color of this Highlighter if this is not immutable.
 void setForeground(java.awt.Color color)
          Sets the foreground color of this Highlighter.
 void setSelectedBackground(java.awt.Color color)
          Sets the selected background color of this Highlighter.
 void setSelectedForeground(java.awt.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

changeEvent

protected transient javax.swing.event.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 javax.swing.event.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
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.

Constructor Detail

Highlighter

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


Highlighter

public Highlighter(java.awt.Color cellBackground,
                   java.awt.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(java.awt.Color cellBackground,
                   java.awt.Color cellForeground,
                   boolean immutable)

Highlighter

public Highlighter(java.awt.Color cellBackground,
                   java.awt.Color cellForeground,
                   java.awt.Color selectedBackground,
                   java.awt.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(java.awt.Color cellBackground,
                   java.awt.Color cellForeground,
                   java.awt.Color selectedBackground,
                   java.awt.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 java.awt.Component highlight(java.awt.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 java.awt.Component doHighlight(java.awt.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(java.awt.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(java.awt.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(java.awt.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 java.awt.Color computeBackground(java.awt.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 java.awt.Color computeForeground(java.awt.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 java.awt.Color computeSelectedBackground(java.awt.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 cope with null!
Returns:
the background color for a selected cell

computeSelectedForeground

protected java.awt.Color computeSelectedForeground(java.awt.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; 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:

getBackground

public java.awt.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(java.awt.Color color)
Sets the background color of this Highlighter if this is not immutable. Does nothing if immutable.

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

getForeground

public java.awt.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(java.awt.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 java.awt.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(java.awt.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 java.awt.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(java.awt.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

addChangeListener

public void addChangeListener(javax.swing.event.ChangeListener l)
Adds a ChangeListener. The change listeners are run each time any one of the Bounded Range model properties changes.

Parameters:
l - the ChangeListener to add
See Also:
removeChangeListener(javax.swing.event.ChangeListener), BoundedRangeModel.addChangeListener(javax.swing.event.ChangeListener)

removeChangeListener

public void removeChangeListener(javax.swing.event.ChangeListener l)
Removes a ChangeListener.

Parameters:
l - the ChangeListener to remove
See Also:
addChangeListener(javax.swing.event.ChangeListener), BoundedRangeModel.removeChangeListener(javax.swing.event.ChangeListener)

getChangeListeners

public javax.swing.event.ChangeListener[] getChangeListeners()
Returns an array of all the change listeners registered on this DefaultBoundedRangeModel.

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.

See Also:
#setRangeProperties, EventListenerList


Copyright © 2005 Sun Microsystems All Rights Reserved.