001/*
002 * $Id: Highlighter.java 3100 2008-10-14 22:33:10Z rah003 $
003 *
004 * Copyright 2006 Sun Microsystems, Inc., 4150 Network Circle,
005 * Santa Clara, California 95054, U.S.A. All rights reserved.
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 * 
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015 * Lesser General Public License for more details.
016 * 
017 * You should have received a copy of the GNU Lesser General Public
018 * License along with this library; if not, write to the Free Software
019 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
020 */
021package org.jdesktop.swingx.decorator;
022
023import java.awt.Component;
024
025import javax.swing.event.ChangeListener;
026
027/**
028 * <code>Highlighter</code> provide a mechanism to modify visual attributes of
029 * cell rendering components. The mechanism is uniform across both rendered and
030 * rendering component types: it is the same for SwingX collection views
031 * (JXTable, JXList, JXTree/Table) and independent of the concrete component
032 * type used for rendering the cell. The view cell state is factored into a
033 * <code>ComponentAdapter</code>.
034 * <p>
035 * 
036 * For example, in data visualization components that support multiple columns
037 * with potentially different types of data, a <code>ColorHighlighter</code>
038 * imparts the same background color consistently across <em>all</em> columns
039 * of the rendered component regardless of the actual cell renderer registered
040 * for any specific column.
041 * <p>
042 * 
043 * The highlightable properties are basically defined by the renderer in use:
044 * only attributes the renderer guarantees to reset on every call are safe to
045 * alter. For SwingX renderering support these are listed in
046 * <code>ComponentProvider</code>.
047 * 
048 * 
049 * Implementations supporting mutable internal state which effects the
050 * decoration must notify its listeners about the change. Typically, the
051 * rendered component installs a listener to its <code>Highlighter</code>s
052 * and triggeres a repaint on notification.
053 * 
054 * @see ComponentAdapter
055 * @see org.jdesktop.swingx.renderer.ComponentProvider
056 * 
057 * @author Ramesh Gupta
058 * @author Jeanette Winzenburg
059 */
060public interface Highlighter {
061
062    /**
063     * Decorates the specified component for the given component
064     * adapter.
065     *
066     * @param renderer the cell rendering component that is to be decorated
067     * @param adapter the ComponentAdapter for this decorate operation
068     * @return the decorated cell rendering component
069     */
070    Component highlight(Component renderer, ComponentAdapter adapter);
071
072    /**
073     * Adds a <code>ChangeListener</code> which are 
074     * notified after changes of any attribute. 
075     *
076     * @param l the ChangeListener to add
077     * @see #removeChangeListener
078     */
079    void addChangeListener(ChangeListener l);
080
081    /**
082     * Removes a <code>ChangeListener</code>.
083     *
084     * @param l the <code>ChangeListener</code> to remove
085     * @see #addChangeListener
086     */
087    void removeChangeListener(ChangeListener l);
088
089    /**
090     * Returns an array of all the change listeners
091     * registered on this <code>LegacyHighlighter</code>.
092     *
093     * @return all of this model's <code>ChangeListener</code>s 
094     *         or an empty
095     *         array if no change listeners are currently registered
096     *
097     * @see #addChangeListener
098     * @see #removeChangeListener
099     *
100     * @since 1.4
101     */
102    ChangeListener[] getChangeListeners();
103
104}