org.jdesktop.swingx.painter.CompoundPainter Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jxmapviewer2 Show documentation
This project is based on the JXMapViewer component of SwingX-WS.
The newest version!
/*
 * $Id: CompoundPainter.java 4147 2012-02-01 17:13:24Z 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.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 java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.List;
import java.util.concurrent.CopyOnWriteArrayList;

//import org.jdesktop.beans.JavaBean;

/**
 * A {@link Painter} implementation composed of an array of Painters.
 * CompoundPainter provides a means for combining several individual
 * Painters, or groups of them, into one logical unit. Each of the
 * Painters 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.
 *
 * 
 *
 * 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:
 * 

 *  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);
 * 

 *
 * @author rbair
 * @param  an optional configuration parameter
 */
//@JavaBean
public class CompoundPainter extends AbstractPainter
{
	private static class Handler implements PropertyChangeListener
	{
		private final WeakReference> ref;

		public Handler(CompoundPainter painter)
		{
			ref = new WeakReference>(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 List> painters = new CopyOnWriteArrayList>();
	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);
	}

	/**
	 * Convenience constructor for creating a CompoundPainter for a list
	 * of painters. A defensive copy of the given array is made, so that future
	 * modification to the list does not result in changes to the CompoundPainter.
	 *
	 * @param painters array of painters, which will be painted in order
	 */
	public CompoundPainter(List> 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(List> painters)
	{
		Collection> old = new ArrayList>(getPainters());

		for (Painter p : old)
		{
			if (p instanceof AbstractPainter)
			{
				((AbstractPainter) p).removePropertyChangeListener(handler);
			}
		}

		this.painters.clear();
		this.painters.addAll(painters);

		for (Painter p : this.painters)
		{
			if (p instanceof AbstractPainter)
			{
				((AbstractPainter) p).addPropertyChangeListener(handler);
			}
		}

		setDirty(true);
		firePropertyChange("painters", old, getPainters());
	}

	/**
	 * 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)
	{
		List> l;

		if (painters == null)
			l = Collections.emptyList();
		else
			l = Arrays.asList(painters);

		setPainters(l);
	}
	
	/**
	 * Adds a painter to the queue of painters
	 * @param painter the painter that is added
	 */
	public void addPainter(Painter painter)
	{
		Collection> old = new ArrayList>(getPainters());
		
		this.painters.add(painter);	
		
		if (painter instanceof AbstractPainter)
		{
			((AbstractPainter) painter).addPropertyChangeListener(handler);
		}

		setDirty(true);
		firePropertyChange("painters", old, getPainters());
	}
	
	/**
	 * Removes a painter from the queue of painters
	 * @param painter the painter that is added
	 */
	public void removePainter(Painter painter)
	{
		Collection> old = new ArrayList>(getPainters());
		
		this.painters.remove(painter);
		
		if (painter instanceof AbstractPainter)
		{
			((AbstractPainter) painter).removePropertyChangeListener(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 Collection> getPainters()
	{
		return Collections.unmodifiableCollection(painters);
	}

	/**
	 * 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);
	}

	/**
	 * Iterates over all child Painters and gives them a chance
	 * to validate themselves. If any of the child painters are dirty, then
	 * this CompoundPainter marks itself as dirty.
	 */
	@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 Painters
	 * should be checked for their dirty flag as part of
	 * processing.

	 * Default value is: true

	 * This should be set to false if the cacheable state
	 * of the child Painters are different from each other.  This
	 * will allow the cacheable == true Painters to
	 * keep their cached image during regular repaints.  In this case,
	 * client code should call {@link #clearCache()} manually when the cacheable
	 * Painters should be updated.
	 * @return the dirty check flag
	 *
	 *
	 * @see #isDirty()
	 */
	public boolean isCheckingDirtyChildPainters()
	{
		return checkForDirtyChildPainters;
	}

	/**
	 * Set the flag used by {@link #isDirty()} to check if the 
	 * child Painters should be checked for their 
	 * dirty flag as part of processing.
	 * @param b the dirty check flag
	 *
	 * @see #isCheckingDirtyChildPainters()
	 * @see #isDirty()
	 */
	public void setCheckingDirtyChildPainters(boolean b)
	{
		boolean old = isCheckingDirtyChildPainters();
		this.checkForDirtyChildPainters = b;
		firePropertyChange("checkingDirtyChildPainters", old, isCheckingDirtyChildPainters());
	}

	/**
	 * This CompoundPainter is dirty if it, or (optionally)
	 * any of its children, are dirty. If the super implementation returns
	 * true, we return true.  Otherwise, if
	 * {@link #isCheckingDirtyChildPainters()} is true, we iterate
	 * over all child Painters and query them to see
	 * if they are dirty. If so, then true is returned. 
	 * Otherwise, we return false.
	 *
	 * @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;
	}

	@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());
		}
	}

	/**
	 * Clears the cache of this Painter, and all child
	 * Painters. 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.
	 *
	 * Call #clearLocalCache if you only want to clear the cache of this
	 * CompoundPainter
	 */
	@Override
	public void clearCache()
	{
		if (!clearLocalCacheOnly)
		{
			for (Painter p : painters)
			{
				if (p instanceof AbstractPainter)
				{
					AbstractPainter ap = (AbstractPainter) p;
					ap.clearCache();
				}
			}
		}
		super.clearCache();
	}

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

	@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();
			}
		}
	}

	@Override
	protected void configureGraphics(Graphics2D g)
	{
		//applies the transform
		AffineTransform tx = getTransform();
		if (tx != null)
		{
			g.setTransform(tx);
		}
	}

	@Override
	protected boolean shouldUseCache()
	{
		return super.shouldUseCache(); // || (painters != null && painters.length > 1);
	}
}