author | prr |
Fri, 23 May 2014 09:05:24 -0700 | |
changeset 24567 | a0ebe5fd56ff |
parent 23010 | 6dadb192ad81 |
child 25201 | 4adc75e0c4e5 |
permissions | -rw-r--r-- |
2658 | 1 |
/* |
23010
6dadb192ad81
8029235: Update copyright year to match last edit in jdk8 jdk repository for 2013
lana
parents:
21982
diff
changeset
|
2 |
* Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. |
2658 | 3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 |
* |
|
5 |
* This code is free software; you can redistribute it and/or modify it |
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2658 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2658 | 10 |
* |
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
|
15 |
* accompanied this code). |
|
16 |
* |
|
17 |
* You should have received a copy of the GNU General Public License version |
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 |
* |
|
5506 | 21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 |
* or visit www.oracle.com if you need additional information or have any |
|
23 |
* questions. |
|
2658 | 24 |
*/ |
25 |
package javax.swing; |
|
26 |
||
27 |
import java.awt.Graphics2D; |
|
28 |
||
29 |
/** |
|
30 |
* <p>A painting delegate. The Painter interface defines exactly one method, |
|
31 |
* <code>paint</code>. It is used in situations where the developer can change |
|
32 |
* the painting routine of a component without having to resort to subclassing |
|
33 |
* the component. It is also generically useful when doing any form of painting |
|
34 |
* delegation.</p> |
|
35 |
* |
|
36 |
* <p><code>Painter</code>s are simply encapsulations of Java2D code and make |
|
37 |
* it fairly trivial to reuse existing <code>Painter</code>s or to combine |
|
38 |
* them together. Implementations of this interface are also trivial to write, |
|
39 |
* such that if you can't find a <code>Painter</code> that does what you need, |
|
40 |
* you can write one with minimal effort. Writing a <code>Painter</code> requires |
|
41 |
* knowledge of Java2D.</p> |
|
42 |
* |
|
43 |
* <p>A <code>Painter</code> may be created with a type parameter. This type will be |
|
44 |
* expected in the <code>paint</code> method. For example, you may wish to write a |
|
45 |
* <code>Painter</code> that only works with subclasses of {@link java.awt.Component}. |
|
46 |
* In that case, when the <code>Painter</code> is declared, you may declare that |
|
47 |
* it requires a <code>Component</code>, allowing the paint method to be type safe. Ex: |
|
9222
7d19f2c40915
7032376: A type parameter isn't seen by using an web browser
rupashka
parents:
5506
diff
changeset
|
48 |
* <pre> |
7d19f2c40915
7032376: A type parameter isn't seen by using an web browser
rupashka
parents:
5506
diff
changeset
|
49 |
* {@code |
7d19f2c40915
7032376: A type parameter isn't seen by using an web browser
rupashka
parents:
5506
diff
changeset
|
50 |
* Painter<Component> p = new Painter<Component>() { |
7d19f2c40915
7032376: A type parameter isn't seen by using an web browser
rupashka
parents:
5506
diff
changeset
|
51 |
* public void paint(Graphics2D g, Component c, int width, int height) { |
7d19f2c40915
7032376: A type parameter isn't seen by using an web browser
rupashka
parents:
5506
diff
changeset
|
52 |
* g.setColor(c.getBackground()); |
7d19f2c40915
7032376: A type parameter isn't seen by using an web browser
rupashka
parents:
5506
diff
changeset
|
53 |
* //and so forth |
2658 | 54 |
* } |
9222
7d19f2c40915
7032376: A type parameter isn't seen by using an web browser
rupashka
parents:
5506
diff
changeset
|
55 |
* } |
7d19f2c40915
7032376: A type parameter isn't seen by using an web browser
rupashka
parents:
5506
diff
changeset
|
56 |
* } |
21982 | 57 |
* </pre> |
2658 | 58 |
* |
59 |
* <p>This interface makes no guarantees of threadsafety.</p> |
|
60 |
* |
|
61 |
* @author rbair |
|
62 |
*/ |
|
63 |
public interface Painter<T> { |
|
64 |
/** |
|
65 |
* <p>Renders to the given {@link java.awt.Graphics2D} object. Implementations |
|
66 |
* of this method <em>may</em> modify state on the <code>Graphics2D</code>, and are not |
|
67 |
* required to restore that state upon completion. In most cases, it is recommended |
|
68 |
* that the caller pass in a scratch graphics object. The <code>Graphics2D</code> |
|
69 |
* must never be null.</p> |
|
70 |
* |
|
71 |
* <p>State on the graphics object may be honored by the <code>paint</code> method, |
|
72 |
* but may not be. For instance, setting the antialiasing rendering hint on the |
|
73 |
* graphics may or may not be respected by the <code>Painter</code> implementation.</p> |
|
74 |
* |
|
75 |
* <p>The supplied object parameter acts as an optional configuration argument. |
|
76 |
* For example, it could be of type <code>Component</code>. A <code>Painter</code> |
|
77 |
* that expected it could then read state from that <code>Component</code> and |
|
78 |
* use the state for painting. For example, an implementation may read the |
|
79 |
* backgroundColor and use that.</p> |
|
80 |
* |
|
81 |
* <p>Generally, to enhance reusability, most standard <code>Painter</code>s ignore |
|
82 |
* this parameter. They can thus be reused in any context. The <code>object</code> |
|
83 |
* may be null. Implementations must not throw a NullPointerException if the object |
|
84 |
* parameter is null.</p> |
|
85 |
* |
|
86 |
* <p>Finally, the <code>width</code> and <code>height</code> arguments specify the |
|
87 |
* width and height that the <code>Painter</code> should paint into. More |
|
88 |
* specifically, the specified width and height instruct the painter that it should |
|
89 |
* paint fully within this width and height. Any specified clip on the |
|
90 |
* <code>g</code> param will further constrain the region.</p> |
|
91 |
* |
|
92 |
* <p>For example, suppose I have a <code>Painter</code> implementation that draws |
|
93 |
* a gradient. The gradient goes from white to black. It "stretches" to fill the |
|
94 |
* painted region. Thus, if I use this <code>Painter</code> to paint a 500 x 500 |
|
95 |
* region, the far left would be black, the far right would be white, and a smooth |
|
96 |
* gradient would be painted between. I could then, without modification, reuse the |
|
97 |
* <code>Painter</code> to paint a region that is 20x20 in size. This region would |
|
98 |
* also be black on the left, white on the right, and a smooth gradient painted |
|
99 |
* between.</p> |
|
100 |
* |
|
101 |
* @param g The Graphics2D to render to. This must not be null. |
|
102 |
* @param object an optional configuration parameter. This may be null. |
|
103 |
* @param width width of the area to paint. |
|
104 |
* @param height height of the area to paint. |
|
105 |
*/ |
|
106 |
public void paint(Graphics2D g, T object, int width, int height); |
|
107 |
} |