org.jdesktop.swingx.decorator
Class LegacyHighlighter

java.lang.Object
  extended by org.jdesktop.swingx.decorator.AbstractHighlighter
      extended by org.jdesktop.swingx.decorator.LegacyHighlighter
All Implemented Interfaces:
Highlighter
Direct Known Subclasses:
AlternateRowHighlighter, ConditionalHighlighter, HierarchicalColumnHighlighter

Deprecated. use ColorHighligher instead

public class LegacyHighlighter
extends AbstractHighlighter

The legacy Highlighter. Note JW: this will be removed "some time" Highlighter overhaul is done. To keep it for now should ease the switching over in legacy code, as all "old" highlighters are direct or indirect descendents.

LegacyHighlighter 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. LegacyHighlighter achieves this by vectoring access to all component-specific state and functionality through a ComponentAdapter object.

The primary purpose of LegacyHighlighter 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 LegacyHighlighter mechanism is orthogonal to the cell rendering mechanism.

To use LegacyHighlighter you must first set up a CompoundHighlighter using an array of LegacyHighlighter 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 CompoundHighlighter 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 LegacyHighlighter 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:

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

  CompoundHighlighter compoundHighlighter = new CompoundHighlighter(highlighters);
  JXTable table = new JXTable();
  table.setHighlighters(compoundHighlighter);
 

The above example allocates an array of LegacyHighlighter 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 LegacyHighlighter.UIHighlighter
          Deprecated. Interface to implement if Highlighter state depends on the LookAndFeel.
 
Field Summary
protected  boolean immutable
          Deprecated. flag to indicate whether the Highlighter is immutable in every respect.
static LegacyHighlighter ledgerBackground
          Deprecated. set the component's background color instead!
static LegacyHighlighter notePadBackground
          Deprecated. set the component's background color instead!
 
Fields inherited from class org.jdesktop.swingx.decorator.AbstractHighlighter
listenerList
 
Constructor Summary
LegacyHighlighter()
          Deprecated. Default constructor for mutable LegacyHighlighter.
LegacyHighlighter(Color cellBackground, Color cellForeground)
          Deprecated. Constructs a mutable LegacyHighlighter with the specified background and foreground colors, selectedBackground and selectedForeground to null.
LegacyHighlighter(Color cellBackground, Color cellForeground, boolean immutable)
          Deprecated.  
LegacyHighlighter(Color cellBackground, Color cellForeground, Color selectedBackground, Color selectedForeground)
          Deprecated. Constructs a mutable LegacyHighlighter with the specified background and foreground colors.
LegacyHighlighter(Color cellBackground, Color cellForeground, Color selectedBackground, Color selectedForeground, boolean immutable)
          Deprecated. Constructs a LegacyHighlighter with the specified background and foreground colors with mutability depending on given flag.
 
Method Summary
 void addChangeListener(ChangeListener l)
          Deprecated. Adds a ChangeListener.
protected  void applyBackground(Component renderer, ComponentAdapter adapter)
          Deprecated. Applies a suitable background for the renderer component within the specified adapter.
protected  void applyForeground(Component renderer, ComponentAdapter adapter)
          Deprecated. Applies a suitable foreground for the renderer component within the specified adapter.
protected  Color computeBackground(Component renderer, ComponentAdapter adapter)
          Deprecated. Computes a suitable background for the renderer component within the specified adapter and returns the computed color.
protected  Color computeForeground(Component renderer, ComponentAdapter adapter)
          Deprecated. 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)
          Deprecated. 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)
          Deprecated. 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)
          Deprecated. 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)
          Deprecated. 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)
          Deprecated. This is the bottleneck decorate method that all highlighters must invoke to decorate the cell renderer.
 Color getBackground()
          Deprecated. Returns the background color of this LegacyHighlighter.
 Color getForeground()
          Deprecated. Returns the foreground color of this LegacyHighlighter.
 Color getSelectedBackground()
          Deprecated. Returns the selected background color of this LegacyHighlighter.
 Color getSelectedForeground()
          Deprecated. Returns the selected foreground color of this LegacyHighlighter.
 Component highlight(Component renderer, ComponentAdapter adapter)
          Deprecated. Decorates the specified cell renderer component for the given component data adapter using highlighters that were previously set for the component.
 boolean isImmutable()
          Deprecated. Returns immutable flag.
 void setBackground(Color color)
          Deprecated. Sets the background color of this LegacyHighlighter and notifies registered ChangeListeners if this is mutable.
 void setForeground(Color color)
          Deprecated. Sets the foreground color of this LegacyHighlighter and notifies registered ChangeListeners if this is mutable.
 void setSelectedBackground(Color color)
          Deprecated. Sets the selected background color of this LegacyHighlighter and notifies registered ChangeListeners if this is mutable.
 void setSelectedForeground(Color color)
          Deprecated. Sets the selected foreground color of this LegacyHighlighter and notifies registered ChangeListeners if this is mutable.
 
Methods inherited from class org.jdesktop.swingx.decorator.AbstractHighlighter
fireStateChanged, getChangeListeners, getHighlightPredicate, removeChangeListener, setHighlightPredicate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ledgerBackground

public static final LegacyHighlighter ledgerBackground
Deprecated. set the component's background color instead!
Predefined LegacyHighlighter 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 LegacyHighlighter notePadBackground
Deprecated. set the component's background color instead!
Predefined LegacyHighlighter 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.


immutable

protected final boolean immutable
Deprecated. 
flag to indicate whether the Highlighter is immutable in every respect.

Constructor Detail

LegacyHighlighter

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


LegacyHighlighter

public LegacyHighlighter(Color cellBackground,
                         Color cellForeground)
Deprecated. 
Constructs a mutable LegacyHighlighter 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

LegacyHighlighter

public LegacyHighlighter(Color cellBackground,
                         Color cellForeground,
                         boolean immutable)
Deprecated. 

LegacyHighlighter

public LegacyHighlighter(Color cellBackground,
                         Color cellForeground,
                         Color selectedBackground,
                         Color selectedForeground)
Deprecated. 
Constructs a mutable LegacyHighlighter 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

LegacyHighlighter

public LegacyHighlighter(Color cellBackground,
                         Color cellForeground,
                         Color selectedBackground,
                         Color selectedForeground,
                         boolean immutable)
Deprecated. 
Constructs a LegacyHighlighter 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)
Deprecated. 
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.

Specified by:
highlight in interface Highlighter
Overrides:
highlight in class AbstractHighlighter
Parameters:
renderer - the cell renderer component that is to be decorated
adapter - the ComponentAdapter for this decorate operation
Returns:
the decorated cell renderer component
See Also:
AbstractHighlighter.doHighlight(Component, ComponentAdapter), AbstractHighlighter.getHighlightPredicate()

doHighlight

protected Component doHighlight(Component renderer,
                                ComponentAdapter adapter)
Deprecated. 
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.

Specified by:
doHighlight in class AbstractHighlighter
Parameters:
renderer - the cell renderer component that is to be decorated
adapter - the ComponentAdapter for this decorate operation
Returns:
the decorated cell renderer component
See Also:
AbstractHighlighter.highlight(Component, ComponentAdapter)

applyBackground

protected void applyBackground(Component renderer,
                               ComponentAdapter adapter)
Deprecated. 
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)
Deprecated. 
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)
Deprecated. 

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)
Deprecated. 

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)
Deprecated. 

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)
Deprecated. 

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)
Deprecated. 

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)
Deprecated. 

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

addChangeListener

public void addChangeListener(ChangeListener l)
Deprecated. 
Adds a ChangeListener. ChangeListeners are notified after changes of any attribute. PENDING: make final once the LegacyHighlighters are removed.

Overridden to not add listener if immutable.

Specified by:
addChangeListener in interface Highlighter
Overrides:
addChangeListener in class AbstractHighlighter
Parameters:
l - the ChangeListener to add
See Also:
AbstractHighlighter.removeChangeListener(javax.swing.event.ChangeListener)

getBackground

public Color getBackground()
Deprecated. 
Returns the background color of this LegacyHighlighter.

Returns:
the background color of this LegacyHighlighter, or null, if no background color has been set

setBackground

public void setBackground(Color color)
Deprecated. 
Sets the background color of this LegacyHighlighter and notifies registered ChangeListeners if this is mutable. Does nothing if immutable.

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

getForeground

public Color getForeground()
Deprecated. 
Returns the foreground color of this LegacyHighlighter.

Returns:
the foreground color of this LegacyHighlighter, or null, if no foreground color has been set

setForeground

public void setForeground(Color color)
Deprecated. 
Sets the foreground color of this LegacyHighlighter and notifies registered ChangeListeners if this is mutable. Does nothing if immutable.

Parameters:
color - the foreground color of this LegacyHighlighter, or null, to clear any existing foreground color

getSelectedBackground

public Color getSelectedBackground()
Deprecated. 
Returns the selected background color of this LegacyHighlighter.

Returns:
the selected background color of this LegacyHighlighter, or null, if no selected background color has been set

setSelectedBackground

public void setSelectedBackground(Color color)
Deprecated. 
Sets the selected background color of this LegacyHighlighter and notifies registered ChangeListeners if this is mutable. Does nothing if immutable.

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

getSelectedForeground

public Color getSelectedForeground()
Deprecated. 
Returns the selected foreground color of this LegacyHighlighter.

Returns:
the selected foreground color of this LegacyHighlighter, or null, if no selected foreground color has been set

setSelectedForeground

public void setSelectedForeground(Color color)
Deprecated. 
Sets the selected foreground color of this LegacyHighlighter and notifies registered ChangeListeners if this is mutable. Does nothing if immutable.

Parameters:
color - the selected foreground color of this LegacyHighlighter, or null, to clear any existing selected foreground color

isImmutable

public final boolean isImmutable()
Deprecated. 
Returns immutable flag. If true, the Highlighter must not change internal state in any way. In this case, no listeners are added and no change events fired.

Returns:
true if none of the setXX methods have any effect