001/* 002 * $Id: Painter.java 3860 2010-10-26 01:14:53Z kschaefe $ 003 * 004 * Copyright 2006 Sun Microsystems, Inc., 4150 Network Circle, 005 * Santa Clara, California 95054, U.S.A. All rights reserved. 006 * 007 * This library is free software; you can redistribute it and/or 008 * modify it under the terms of the GNU Lesser General Public 009 * License as published by the Free Software Foundation; either 010 * version 2.1 of the License, or (at your option) any later version. 011 * 012 * This library is distributed in the hope that it will be useful, 013 * but WITHOUT ANY WARRANTY; without even the implied warranty of 014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 015 * Lesser General Public License for more details. 016 * 017 * You should have received a copy of the GNU Lesser General Public 018 * License along with this library; if not, write to the Free Software 019 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 020 */ 021 022package org.jdesktop.swingx.painter; 023 024import java.awt.Graphics2D; 025 026/** 027 * <p>A painting delegate. The Painter interface defines exactly one method, 028 * <code>paint</code>. It is used in situations where the developer can change 029 * the painting routine of a component without having to resort to subclassing 030 * the component.</p> 031 * 032 * <p><code>Painter</code>s are simply encapsulations of Java2D code and make 033 * it fairly trivial to reuse existing <code>Painter</code>s or to combine 034 * them together. Implementations of this interface are also trivial to write, 035 * such that if you can't find a <code>Painter</code> that does what you need, 036 * you can write one with minimal effort. Writing a <code>Painter</code> requires 037 * knowledge of Java2D.</p> 038 * 039 * <p>A <code>Painter</code> may be created with a type parameter. This type will be 040 * expected in the <code>paint</code> method. For example, you may wish to write a 041 * <code>Painter</code> that only works with subclasses of {@link java.awt.Component}. 042 * In that case, when the <code>Painter</code> is declared, you may declare that 043 * it requires a <code>Component</code>, allowing the paint method to be type safe. Ex: 044 * <pre><code> 045 * Painter<Component> p = new Painter<Component>() { 046 * public void paint(Graphics2D g, Component c, int width, int height) { 047 * g.setColor(c.getBackground()); 048 * //and so forth 049 * } 050 * } 051 * </code></pre></p> 052 * 053 * <p>This class is <strong>not</strong> threadsafe.</p> 054 * 055 * @author rbair 056 * @see AbstractPainter 057 * @see CompoundPainter 058 */ 059public interface Painter<T> { 060 /** 061 * <p>Renders to the given {@link java.awt.Graphics2D} object. Implementations 062 * of this method <em>may</em> modify state on the <code>Graphics2D</code>, and are not 063 * required to restore that state upon completion. In most cases, it is recommended 064 * that the caller pass in a scratch graphics object. The <code>Graphics2D</code> 065 * must never be null.</p> 066 * 067 * <p>State on the graphics object may be honored by the <code>paint</code> method, 068 * but may not be. For instance, setting the antialiasing rendering hint on the 069 * graphics may or may not be respected by the <code>Painter</code> implementation.</p> 070 * 071 * <p>The supplied object parameter acts as an optional configuration argument. 072 * For example, it could be of type <code>Component</code>. A <code>Painter</code> 073 * that expected it could then read state from that <code>Component</code> and 074 * use the state for painting. For example, an implementation may read the 075 * backgroundColor and use that.</p> 076 * 077 * <p>Generally, to enhance reusability, most standard <code>Painter</code>s ignore 078 * this parameter. They can thus be reused in any context. The <code>object</code> 079 * may be null. Implementations must not throw a NullPointerException if the object 080 * parameter is null.</p> 081 * 082 * <p>Finally, the <code>width</code> and <code>height</code> arguments specify the 083 * width and height that the <code>Painter</code> should paint into. More 084 * specifically, the specified width and height instruct the painter that it should 085 * paint fully within this width and height. Any specified clip on the 086 * <code>g</code> param will further constrain the region.</p> 087 * 088 * <p>For example, suppose I have a <code>Painter</code> implementation that draws 089 * a gradient. The gradient goes from white to black. It "stretches" to fill the 090 * painted region. Thus, if I use this <code>Painter</code> to paint a 500 x 500 091 * region, the far left would be black, the far right would be white, and a smooth 092 * gradient would be painted between. I could then, without modification, reuse the 093 * <code>Painter</code> to paint a region that is 20x20 in size. This region would 094 * also be black on the left, white on the right, and a smooth gradient painted 095 * between.</p> 096 * 097 * @param g The Graphics2D to render to. This must not be null. 098 * @param object an optional configuration parameter. This may be null. 099 * @param width width of the area to paint. 100 * @param height height of the area to paint. 101 */ 102 public void paint(Graphics2D g, T object, int width, int height); 103}