/*
* $Id: CompoundPainter.java 3730 2010-07-20 15:10:25Z kschaefe $
*
* 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.hdesktop.swingx.painter;
import java.awt.Graphics2D;
import java.awt.geom.AffineTransform;
import java.beans.PropertyChangeEvent;
import java.beans.PropertyChangeListener;
import java.lang.ref.WeakReference;
/**
* <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
*/
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(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());
}
/**
* <p>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>.</p>
*
* {@inheritDoc}
* {@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 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 (isCacheable() && painters != null && painters.length > 0) || super.shouldUseCache();
}
}