org.jdesktop.swingx.painter
Class AbstractPainter<T>

java.lang.Object
  org.jdesktop.beans.AbstractBean
      org.jdesktop.swingx.painter.AbstractPainter<T>

All Implemented Interfaces:

Painter<T>

Direct Known Subclasses:

AbstractLayoutPainter, BusyPainter, CheckerboardPainter, CompoundPainter, GlossPainter, JXMultiSplitPane.DividerPainter, PinstripePainter

public abstract class AbstractPainter<T>
extends AbstractBean
implements Painter<T>

A convenient base class from which concrete Painter implementations may extend. It extends AbstractBean as a convenience for adding property change notification support. In addition, AbstractPainter provides subclasses with the ability to cacheable painting operations, configure the drawing surface with common settings (such as antialiasing and interpolation), and toggle whether a subclass paints or not via the visibility property.

Subclasses of AbstractPainter generally need only override the doPaint(Graphics2D, Object, int, int) method. If a subclass requires more control over whether cacheing is enabled, or for configuring the graphics state, then it may override the appropriate protected methods to interpose its own behavior.

For example, here is the doPaint method of a simple Painter that paints an opaque rectangle:

  public void doPaint(Graphics2D g, T obj, int width, int height) {
      g.setPaint(Color.BLUE);
      g.fillRect(0, 0, width, height);
  }
 

Nested Class Summary

static class

AbstractPainter.Interpolation An enum representing the possible interpolation values of Bicubic, Bilinear, and Nearest Neighbor.

Constructor Summary

AbstractPainter()
Creates a new instance of AbstractPainter.

AbstractPainter(boolean cacheable)
Creates a new instance of AbstractPainter.

Method Summary

void	clearCache() Call this method to clear the cacheable.
protected void	configureGraphics(Graphics2D g) This method is called by the paint method prior to any drawing operations to configure the drawing surface.
protected abstract void	doPaint(Graphics2D g, T object, int width, int height) Subclasses must implement this method and perform custom painting operations here.
BufferedImageOp[]	getFilters() A defensive copy of the Effects to apply to the results of the AbstractPainter's painting operation.
AbstractPainter.Interpolation	getInterpolation() Gets the current interpolation setting.
boolean	isAntialiasing() Returns if antialiasing is turned on or not.
boolean	isCacheable() Gets whether this AbstractPainter can be cached as an image.
protected boolean	isDirty() Ye olde dirty bit.
boolean	isVisible() Gets the visible property.
void	paint(Graphics2D g, T obj, int width, int height) Renders to the given Graphics2D object.
void	setAntialiasing(boolean value) Sets the antialiasing setting.
void	setCacheable(boolean cacheable) Sets whether this AbstractPainter can be cached as an image.
protected void	setDirty(boolean d) Sets the dirty bit.
void	setFilters(BufferedImageOp... effects) A convenience method for specifying the filters to use based on BufferedImageOps.
void	setInterpolation(AbstractPainter.Interpolation value) Sets a new value for the interpolation setting.
void	setVisible(boolean visible) Sets the visible property.
protected boolean	shouldUseCache() Returns true if the painter should use caching.
protected void	validate(T object) Called to allow Painter subclasses a chance to see if any state in the given object has changed from the last paint operation.

Methods inherited from class org.jdesktop.beans.AbstractBean

addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, clone, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, hasPropertyChangeListeners, hasVetoableChangeListeners, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractPainter

public AbstractPainter()

Creates a new instance of AbstractPainter.

AbstractPainter

public AbstractPainter(boolean cacheable)

Creates a new instance of AbstractPainter.

Parameters:

cacheable - indicates if this painter should be cacheable

Method Detail

getFilters

public final BufferedImageOp[] getFilters()

A defensive copy of the Effects to apply to the results of the AbstractPainter's painting operation. The array may be empty but it will never be null.

Returns:

the array of filters applied to this painter

setFilters

public void setFilters(BufferedImageOp... effects)

A convenience method for specifying the filters to use based on BufferedImageOps. These will each be individually wrapped by an ImageFilter and then setFilters(Effect... filters) will be called with the resulting array

Parameters:

effects - the BufferedImageOps to wrap as filters

isAntialiasing

public boolean isAntialiasing()

Returns if antialiasing is turned on or not. The default value is true. This is a bound property.

Returns:

the current antialiasing setting

setAntialiasing

public void setAntialiasing(boolean value)

Sets the antialiasing setting. This is a bound property.

Parameters:

value - the new antialiasing setting

getInterpolation

public AbstractPainter.Interpolation getInterpolation()

Gets the current interpolation setting. This property determines if interpolation will be used when drawing scaled images. @see java.awt.RenderingHints.KEY_INTERPOLATION.

Returns:

the current interpolation setting

setInterpolation

public void setInterpolation(AbstractPainter.Interpolation value)

Sets a new value for the interpolation setting. This setting determines if interpolation should be used when drawing scaled images. @see java.awt.RenderingHints.KEY_INTERPOLATION.

Parameters:

value - the new interpolation setting

isVisible

public boolean isVisible()

Gets the visible property. This controls if the painter should paint itself. It is true by default. Setting visible to false is good when you want to temporarily turn off a painter. An example of this is a painter that you only use when a button is highlighted.

Returns:

current value of visible property

setVisible

public void setVisible(boolean visible)

Sets the visible property. This controls if the painter should paint itself. It is true by default. Setting visible to false is good when you want to temporarily turn off a painter. An example of this is a painter that you only use when a button is highlighted.

Parameters:

visible - New value of visible property.

isCacheable

public boolean isCacheable()

Gets whether this AbstractPainter can be cached as an image. If cacheing is enabled, then it is the responsibility of the developer to invalidate the painter (via clearCache()) if external state has changed in such a way that the painter is invalidated and needs to be repainted.

Returns:

whether this is cacheable

setCacheable

public void setCacheable(boolean cacheable)

Sets whether this AbstractPainter can be cached as an image. If true, this is treated as a hint. That is, a cacheable may or may not be used. The shouldUseCache() method actually determines whether the cacheable is used. However, if false, then this is treated as an absolute value. That is, no cacheable will be used.

If set to false, then #clearCache is called to free system resources.

Parameters:

cacheable -

clearCache

public void clearCache()

Call this method to clear the cacheable. This may be called whether there is a cacheable being used or not. If cleared, on the next call to paint, the painting routines will be called.

SubclassesIf overridden in subclasses, you must call super.clearCache, or physical resources (such as an Image) may leak.

validate

protected void validate(T object)

Called to allow Painter subclasses a chance to see if any state in the given object has changed from the last paint operation. If it has, then the Painter has a chance to mark itself as dirty, thus causing a repaint, even if cached.

Parameters:

object -

isDirty

protected boolean isDirty()

Ye olde dirty bit. If true, then the painter is considered dirty and in need of being repainted. This is a bound property.

Returns:

true if the painter state has changed and the painter needs to be repainted.

setDirty

protected void setDirty(boolean d)

Sets the dirty bit. If true, then the painter is considered dirty, and the cache will be cleared. This property is bound.

Parameters:

d - whether this Painter is dirty.

shouldUseCache

protected boolean shouldUseCache()

Returns true if the painter should use caching. This method allows subclasses to specify the heuristics regarding whether to cache or not. If a Painter has intelligent rules regarding painting times, and can more accurately indicate whether it should be cached, it could implement that logic in this method.

Returns:

whether or not a cache should be used

configureGraphics

protected void configureGraphics(Graphics2D g)

This method is called by the paint method prior to any drawing operations to configure the drawing surface. The default implementation sets the rendering hints that have been specified for this AbstractPainter.

This method can be overriden by subclasses to modify the drawing surface before any painting happens.

Parameters:

g - the graphics surface to configure. This will never be null.

See Also:

paint(Graphics2D, Object, int, int)

doPaint

protected abstract void doPaint(Graphics2D g,
                                T object,
                                int width,
                                int height)

Subclasses must implement this method and perform custom painting operations here.

Parameters:

width -

height -

g - The Graphics2D object in which to paint

object -

paint

public final void paint(Graphics2D g,
                        T obj,
                        int width,
                        int height)

Description copied from interface: Painter

Renders to the given Graphics2D object. Implementations of this method may modify state on the Graphics2D, and are not required to restore that state upon completion. In most cases, it is recommended that the caller pass in a scratch graphics object. The Graphics2D must never be null.

State on the graphics object may be honored by the paint method, but may not be. For instance, setting the antialiasing rendering hint on the graphics may or may not be respected by the Painter implementation.

The supplied object parameter acts as an optional configuration argument. For example, it could be of type Component. A Painter that expected it could then read state from that Component and use the state for painting. For example, an implementation may read the backgroundColor and use that.

Generally, to enhance reusability, most standard Painters ignore this parameter. They can thus be reused in any context. The object may be null. Implementations must not throw a NullPointerException if the object parameter is null.

Finally, the width and height arguments specify the width and height that the Painter should paint into. More specifically, the specified width and height instruct the painter that it should paint fully within this width and height. Any specified clip on the g param will further constrain the region.

For example, suppose I have a Painter implementation that draws a gradient. The gradient goes from white to black. It "stretches" to fill the painted region. Thus, if I use this Painter to paint a 500 x 500 region, the far left would be black, the far right would be white, and a smooth gradient would be painted between. I could then, without modification, reuse the Painter to paint a region that is 20x20 in size. This region would also be black on the left, white on the right, and a smooth gradient painted between.

Specified by:

paint in interface Painter<T>

Parameters:

g - The Graphics2D to render to. This must not be null.

obj - an optional configuration parameter. This may be null.

width - width of the area to paint.

height - height of the area to paint.