swingx-master/swingx-painters/src/main/java/org/jdesktop/swingx/painter/CompoundPainter.java
/*
 * $Id$
 *
 * Copyright 2004 Sun Microsystems, Inc., 4150 Network Circle,
 * Santa Clara, California 95054, U.S.A. All rights reserved.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */

package org.jdesktop.swingx.painter;

import java.awt.Graphics2D;
import java.awt.geom.AffineTransform;
import java.beans.PropertyChangeEvent;
import java.beans.PropertyChangeListener;
import java.lang.ref.WeakReference;

import org.jdesktop.beans.JavaBean;

/**
 * <p>A {@link Painter} implementation composed of an array of <code>Painter</code>s.
 * <code>CompoundPainter</code> provides a means for combining several individual
 * <code>Painter</code>s, or groups of them, into one logical unit. Each of the
 * <code>Painter</code>s are executed in order. BufferedImageOp filter effects can
 * be applied to them together as a whole. The entire set of painting operations
 * may be cached together.</p>
 *
 * <p></p>
 *
 * <p>For example, if I want to create a CompoundPainter that started with a blue
 * background, had pinstripes on it running at a 45 degree angle, and those
 * pinstripes appeared to "fade in" from left to right, I would write the following:
 * <pre><code>
 *  Color blue = new Color(0x417DDD);
 *  Color translucent = new Color(blue.getRed(), blue.getGreen(), blue.getBlue(), 0);
 *  panel.setBackground(blue);
 *  panel.setForeground(Color.LIGHT_GRAY);
 *  GradientPaint blueToTranslucent = new GradientPaint(
 *    new Point2D.Double(.4, 0),
 *    blue,
 *    new Point2D.Double(1, 0),
 *    translucent);
 *  MattePainter veil = new MattePainter(blueToTranslucent);
 *  veil.setPaintStretched(true);
 *  Painter pinstripes = new PinstripePainter(45);
 *  Painter backgroundPainter = new RectanglePainter(this.getBackground(), null);
 *  Painter p = new CompoundPainter(backgroundPainter, pinstripes, veil);
 *  panel.setBackgroundPainter(p);
 * </code></pre></p>
 *
 * @author rbair
 */
@JavaBean
@SuppressWarnings("nls")
public class CompoundPainter<T> extends AbstractPainter<T> {
    private static class Handler implements PropertyChangeListener {
        private final WeakReference<CompoundPainter<?>> ref;
        
        public Handler(CompoundPainter<?> painter) {
            ref = new WeakReference<CompoundPainter<?>>(painter);
        }
        
        /**
         * {@inheritDoc}
         */
        @Override
        public void propertyChange(PropertyChangeEvent evt) {
            CompoundPainter<?> painter = ref.get();
            
            if (painter == null) {
                AbstractPainter<?> src = (AbstractPainter<?>) evt.getSource();
                src.removePropertyChangeListener(this);
            } else {
                String property = evt.getPropertyName();
                
                if ("dirty".equals(property) && evt.getNewValue() == Boolean.FALSE) {
                    return;
                }
                
                painter.setDirty(true);
            }
        }
    }
    
    private Handler handler;
    
    private Painter[] painters = new Painter[0];
    private AffineTransform transform;
    private boolean clipPreserved = false;

    private boolean checkForDirtyChildPainters = true;

    /** Creates a new instance of CompoundPainter */
    public CompoundPainter() {
        this((Painter[]) null);
    }
    
    /**
     * Convenience constructor for creating a CompoundPainter for an array
     * of painters. A defensive copy of the given array is made, so that future
     * modification to the array does not result in changes to the CompoundPainter.
     *
     * @param painters array of painters, which will be painted in order
     */
    public CompoundPainter(Painter... painters) {
        handler = new Handler(this);
        
        setPainters(painters);
    }
    
    /**
     * Sets the array of Painters to use. These painters will be executed in
     * order. A null value will be treated as an empty array. To prevent unexpected 
     * behavior all values in provided array are copied to internally held array. 
     * Any changes to the original array will not be reflected.
     *
     * @param painters array of painters, which will be painted in order
     */
    public void setPainters(Painter... painters) {
        Painter[] old = getPainters();
        
        for (Painter p : old) {
            if (p instanceof AbstractPainter) {
                ((AbstractPainter<?>) p).removePropertyChangeListener(handler);
            }
        }
        
        this.painters = new Painter[painters == null ? 0 : painters.length];
        if (painters != null) {
            System.arraycopy(painters, 0, this.painters, 0, this.painters.length);
        }
        
        for (Painter<?> p : this.painters) {
            if (p instanceof AbstractPainter) {
                ((AbstractPainter<?>) p).addPropertyChangeListener(handler);
            }
        }
        
        setDirty(true);
        firePropertyChange("painters", old, getPainters());
    }
    
    /**
     * Gets the array of painters used by this CompoundPainter
     * @return a defensive copy of the painters used by this CompoundPainter.
     *         This will never be null.
     */
    public final Painter[] getPainters() {
        Painter[] results = new Painter[painters.length];
        System.arraycopy(painters, 0, results, 0, results.length);
        return results;
    }
    
    
    /**
     * Indicates if the clip produced by any painter is left set once it finishes painting. 
     * Normally the clip will be reset between each painter. Setting clipPreserved to
     * true can be used to let one painter mask other painters that come after it.
     * @return if the clip should be preserved
     * @see #setClipPreserved(boolean)
     */
    public boolean isClipPreserved() {
        return clipPreserved;
    }
    
    /**
     * Sets if the clip should be preserved.
     * Normally the clip will be reset between each painter. Setting clipPreserved to
     * true can be used to let one painter mask other painters that come after it.
     * 
     * @param shouldRestoreState new value of the clipPreserved property
     * @see #isClipPreserved()
     */
    public void setClipPreserved(boolean shouldRestoreState) {
        boolean oldShouldRestoreState = isClipPreserved();
        this.clipPreserved = shouldRestoreState;
        setDirty(true);
        firePropertyChange("clipPreserved",oldShouldRestoreState,shouldRestoreState);
    }

    /**
     * Gets the current transform applied to all painters in this CompoundPainter. May be null.
     * @return the current AffineTransform
     */
    public AffineTransform getTransform() {
        return transform;
    }

    /**
     * Set a transform to be applied to all painters contained in this CompoundPainter
     * @param transform a new AffineTransform
     */
    public void setTransform(AffineTransform transform) {
        AffineTransform old = getTransform();
        this.transform = transform;
        setDirty(true);
        firePropertyChange("transform",old,transform);
    }
    
    /**
     * <p>Iterates over all child <code>Painter</code>s and gives them a chance
     * to validate themselves. If any of the child painters are dirty, then
     * this <code>CompoundPainter</code> marks itself as dirty.</p>
     *
     * {@inheritDoc}
     */
    @Override
    protected void validate(T object) {
        boolean dirty = false;
        for (Painter<?> p : painters) {
            if (p instanceof AbstractPainter) {
                AbstractPainter ap = (AbstractPainter) p;
                ap.validate(object);
                if (ap.isDirty()) {
                    dirty = true;
                    break;
                }
            }
        }
        clearLocalCacheOnly = true;
        setDirty(dirty); //super will call clear cache
        clearLocalCacheOnly = false;
    }

    //indicates whether the local cache should be cleared only, as opposed to the
    //cache's of all of the children. This is needed to optimize the caching strategy
    //when, during validate, the CompoundPainter is marked as dirty
    private boolean clearLocalCacheOnly = false;

    /**
     * Used by {@link #isDirty()} to check if the child <code>Painter</code>s
     * should be checked for their <code>dirty</code> flag as part of
     * processing.<br>
     * Default value is: <code>true</code><br>
     * This should be set to </code>false</code> if the cacheable state
     * of the child <code>Painter</code>s are different from each other.  This
     * will allow the cacheable == <code>true</code> <code>Painter</code>s to
     * keep their cached image during regular repaints.  In this case,
     * client code should call {@link #clearCache()} manually when the cacheable
     * <code>Painter</code>s should be updated.
     *
     *
     * @see #isDirty()
     */
    public boolean isCheckingDirtyChildPainters() {
        return checkForDirtyChildPainters;
    }
    /**
     * Set the flag used by {@link #isDirty()} to check if the 
     * child <code>Painter</code>s should be checked for their 
     * <code>dirty</code> flag as part of processing.
     *
     * @see #isCheckingDirtyChildPainters()
     * @see #isDirty()
     */
    public void setCheckingDirtyChildPainters(boolean b) {
        boolean old = isCheckingDirtyChildPainters();
        this.checkForDirtyChildPainters = b;
        firePropertyChange("checkingDirtyChildPainters",old, isCheckingDirtyChildPainters());
    }

    /**
     * {@inheritDoc}
     * 
     * @impl This <code>CompoundPainter</code> is dirty if it, or (optionally) any of its children,
     *       are dirty. If the super implementation returns <code>true</code>, we return
     *       <code>true</code>. Otherwise, if {@link #isCheckingDirtyChildPainters()} is
     *       <code>true</code>, we iterate over all child <code>Painter</code>s and query them to
     *       see if they are dirty. If so, then <code>true</code> is returned. Otherwise, we return
     *       <code>false</code>.
     * @see #isCheckingDirtyChildPainters()
     */
    @Override
    protected boolean isDirty() {
        boolean dirty = super.isDirty();
        if (dirty) {
            return true;
        } 
        else if (isCheckingDirtyChildPainters()) {
            for (Painter<?> p : painters) {
                if (p instanceof AbstractPainter) {
                    AbstractPainter<?> ap = (AbstractPainter<?>) p;
                    if (ap.isDirty()) {
                        return true;
                    }
                }
            }
        }
        return false;
    }
    
    /**
     * {@inheritDoc}
     */
    @Override
    protected void setDirty(boolean d) {
        boolean old = super.isDirty();
        boolean ours = isDirty();
        
        super.setDirty(d);
        
        //must perform this check to ensure we do not double notify
        if (d != old && d == ours) {
            firePropertyChange("dirty", old, isDirty());
        }
    }

    /**
     * <p>Clears the cache of this <code>Painter</code>, and all child
     * <code>Painters</code>. This is done to ensure that resources
     * are collected, even if clearCache is called by some framework
     * or other code that doesn't realize this is a CompoundPainter.</p>
     *
     * <p>Call #clearLocalCache if you only want to clear the cache of this
     * <code>CompoundPainter</code>
     *
     * {@inheritDoc}
     */
    @Override
    public void clearCache() {
        if (!clearLocalCacheOnly) {
            for (Painter<?> p : painters) {
                if (p instanceof AbstractPainter) {
                    AbstractPainter<?> ap = (AbstractPainter<?>) p;
                    ap.clearCache();
                }
            }
        }
        super.clearCache();
    }

    /**
     * <p>Clears the cache of this painter only, and not of any of the children.</p>
     */
    public void clearLocalCache() {
        super.clearCache();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    protected void doPaint(Graphics2D g, T component, int width, int height) {
        for (Painter<T> p : getPainters()) {
            Graphics2D temp = (Graphics2D) g.create();
            
            try {
                p.paint(temp, component, width, height);
            if(isClipPreserved()) {
                g.setClip(temp.getClip());
            }
            } finally {
                temp.dispose();
            }
        }
    }

    /**
     * {@inheritDoc}
     */
    @Override
    protected void configureGraphics(Graphics2D g) {
        //applies the transform
        AffineTransform tx = getTransform();
        if (tx != null) {
            g.setTransform(tx);
        }
    }
    
    /**
     * {@inheritDoc}
     */
    @Override
    protected boolean shouldUseCache() {
        return super.shouldUseCache(); // || (painters != null && painters.length > 1);
    }
}
