Package org.jdesktop.swingx.painter

Class AbstractPainter<T>

  • All Implemented Interfaces:
    Painter<T>
    Direct Known Subclasses:
    AbstractLayoutPainter, BusyPainter, CheckerboardPainter, CompoundPainter, GlossPainter, JXMultiSplitPane.DividerPainter, PinstripePainter, TextCrossingPainter
    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 caching 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);
  }

    • Field Detail

      • cachedImage

        private transient java.lang.ref.SoftReference<java.awt.image.BufferedImage> cachedImage
        The cached image, if shouldUseCache() returns true

      • cacheCleared

        private boolean cacheCleared

      • cacheable

        private boolean cacheable

      • dirty

        private boolean dirty

      • filters

        private java.awt.image.BufferedImageOp[] filters

      • antialiasing

        private boolean antialiasing

      • visible

        private boolean visible

      • inPaintContext

        private boolean inPaintContext

    • 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 java.awt.image.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​(java.awt.image.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 caching 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.

      • isCacheCleared

        boolean isCacheCleared()
        Only made package private for testing. Don't call this method outside of this class! This is NOT a bound property

      • 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.

      • isInPaintContext

        boolean isInPaintContext()

      • setInPaintContext

        void setInPaintContext​(boolean inPaintContext)

      • 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​(java.awt.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 overridden 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​(java.awt.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​(java.awt.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.