KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > java > swing > Painter


1 /*
2  * @(#)Painter.java 1.2 07/12/12
3  *
4  * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7 package com.sun.java.swing;
8
9 import java.awt.Graphics2D JavaDoc;
10
11 /**
12  * <p>A painting delegate. The Painter interface defines exactly one method,
13  * <code>paint</code>. It is used in situations where the developer can change
14  * the painting routine of a component without having to resort to subclassing
15  * the component. It is also generically useful when doing any form of painting
16  * delegation.</p>
17  *
18  * <p><code>Painter</code>s are simply encapsulations of Java2D code and make
19  * it fairly trivial to reuse existing <code>Painter</code>s or to combine
20  * them together. Implementations of this interface are also trivial to write,
21  * such that if you can't find a <code>Painter</code> that does what you need,
22  * you can write one with minimal effort. Writing a <code>Painter</code> requires
23  * knowledge of Java2D.</p>
24  *
25  * <p>A <code>Painter</code> may be created with a type parameter. This type will be
26  * expected in the <code>paint</code> method. For example, you may wish to write a
27  * <code>Painter</code> that only works with subclasses of {@link java.awt.Component}.
28  * In that case, when the <code>Painter</code> is declared, you may declare that
29  * it requires a <code>Component</code>, allowing the paint method to be type safe. Ex:
30  * <pre><code>
31  * Painter<Component> p = new Painter<Component>() {
32  * public void paint(Graphics2D g, Component c, int width, int height) {
33  * g.setColor(c.getBackground());
34  * //and so forth
35  * }
36  * }
37  * </code></pre></p>
38  *
39  * <p>This interface makes no guarantees of threadsafety.</p>
40  *
41  * @author rbair
42  */
43 public interface Painter<T> {
44     /**
45      * <p>Renders to the given {@link java.awt.Graphics2D} object. Implementations
46      * of this method <em>may</em> modify state on the <code>Graphics2D</code>, and are not
47      * required to restore that state upon completion. In most cases, it is recommended
48      * that the caller pass in a scratch graphics object. The <code>Graphics2D</code>
49      * must never be null.</p>
50      *
51      * <p>State on the graphics object may be honored by the <code>paint</code> method,
52      * but may not be. For instance, setting the antialiasing rendering hint on the
53      * graphics may or may not be respected by the <code>Painter</code> implementation.</p>
54      *
55      * <p>The supplied object parameter acts as an optional configuration argument.
56      * For example, it could be of type <code>Component</code>. A <code>Painter</code>
57      * that expected it could then read state from that <code>Component</code> and
58      * use the state for painting. For example, an implementation may read the
59      * backgroundColor and use that.</p>
60      *
61      * <p>Generally, to enhance reusability, most standard <code>Painter</code>s ignore
62      * this parameter. They can thus be reused in any context. The <code>object</code>
63      * may be null. Implementations must not throw a NullPointerException if the object
64      * parameter is null.</p>
65      *
66      * <p>Finally, the <code>width</code> and <code>height</code> arguments specify the
67      * width and height that the <code>Painter</code> should paint into. More
68      * specifically, the specified width and height instruct the painter that it should
69      * paint fully within this width and height. Any specified clip on the
70      * <code>g</code> param will further constrain the region.</p>
71      *
72      * <p>For example, suppose I have a <code>Painter</code> implementation that draws
73      * a gradient. The gradient goes from white to black. It "stretches" to fill the
74      * painted region. Thus, if I use this <code>Painter</code> to paint a 500 x 500
75      * region, the far left would be black, the far right would be white, and a smooth
76      * gradient would be painted between. I could then, without modification, reuse the
77      * <code>Painter</code> to paint a region that is 20x20 in size. This region would
78      * also be black on the left, white on the right, and a smooth gradient painted
79      * between.</p>
80      *
81      * @param g The Graphics2D to render to. This must not be null.
82      * @param object an optional configuration parameter. This may be null.
83      * @param width width of the area to paint.
84      * @param height height of the area to paint.
85      */
86     public void paint(Graphics2D JavaDoc g, T object, int width, int height);
87 }
88
Popular Tags