001 /* LineBorder.java --
002 Copyright (C) 2003 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package javax.swing.border;
040
041 import java.awt.Color;
042 import java.awt.Component;
043 import java.awt.Graphics;
044 import java.awt.Insets;
045
046
047 /**
048 * A border that consists of a line whose thickness and color can be
049 * specified. There also is a variant with rounded corners.
050 *
051 * @author Sascha Brawer (brawer@dandelis.ch)
052 */
053 public class LineBorder extends AbstractBorder
054 {
055 /**
056 * Determined using the <code>serialver</code> tool
057 * of Apple/Sun JDK 1.3.1 on MacOS X 10.1.5.
058 */
059 static final long serialVersionUID = -787563427772288970L;
060
061
062 /**
063 * A shared instance of a black, one pixel thick, plain LineBorder.
064 * The singleton object is lazily created by {@link
065 * #createBlackLineBorder()} upon its first invocation.
066 */
067 private static LineBorder blackLineBorder;
068
069
070 /**
071 * A shared instance of a gray, one pixel thick, plain LineBorder.
072 * The singleton object is lazily created by {@link
073 * #createGrayLineBorder()} upon its first invocation.
074 */
075 private static LineBorder grayLineBorder;
076
077
078 /**
079 * The width of the line in pixels.
080 */
081 protected int thickness;
082
083
084 /**
085 * The color of the line.
086 */
087 protected Color lineColor;
088
089
090 /**
091 * Indicates whether the line is drawn with rounded corners
092 * (<code>true</code>) or not ((<code>false</code>).
093 */
094 protected boolean roundedCorners;
095
096
097 /**
098 * Constructs a LineBorder given its color. The border will be one
099 * pixel thick and have plain corners.
100 *
101 * @param color the color for drawing the border.
102 *
103 * @see #LineBorder(java.awt.Color, int, boolean)
104 */
105 public LineBorder(Color color)
106 {
107 this(color, /* thickness */ 1, /* roundedCorners */ false);
108 }
109
110
111 /**
112 * Constructs a LineBorder given its color and thickness. The
113 * border will have plain corners.
114 *
115 * @param color the color for drawing the border.
116 * @param thickness the width of the line in pixels.
117 *
118 * @see #LineBorder(java.awt.Color, int, boolean)
119 */
120 public LineBorder(Color color, int thickness)
121 {
122 this (color, thickness, /* roundedCorners */ false);
123 }
124
125
126 /**
127 * Constructs a LineBorder given its color, thickness, and whether
128 * it has rounded corners.
129 *
130 * <p><img src="doc-files/LineBorder-1.png" width="500" height="200"
131 * alt="[An illustration of two LineBorders]" />
132 *
133 * <p>Note that the enlarged view in the right-hand picture shows
134 * that the implementation draws one more pixel than specified,
135 * provided that <code>roundedCorders</code> is <code>true</code>
136 * and anti-aliasing is turned on while painting. While this might
137 * be considered a bug, the Sun reference implementation (at least
138 * JDK 1.3.1 on Apple MacOS X 10.1.5) can be observed to fill
139 * exactly the same pixels as shown above. The GNU Classpath
140 * LineBorder replicates the observed behavior of the Sun
141 * implementation.
142 *
143 * @param color the color for drawing the border.
144 * @param thickness the width of the line in pixels.
145 * @param roundedCorners <code>true</code> for rounded corners,
146 * <code>false</code> for plain corners.
147 *
148 * @since 1.3
149 */
150 // For the bug mentioned in the JavaDoc, please see also the comment
151 // in the paintBorder method below.
152 //
153 public LineBorder(Color color, int thickness, boolean roundedCorners)
154 {
155 if ((color == null) || (thickness < 0))
156 throw new IllegalArgumentException();
157
158 this.lineColor = color;
159 this.thickness = thickness;
160 this.roundedCorners = roundedCorners;
161 }
162
163
164 /**
165 * Returns a black, one pixel thick, plain {@link LineBorder}. The method
166 * may always return the same (singleton) {@link LineBorder} instance.
167 *
168 * @return The border.
169 */
170 public static Border createBlackLineBorder()
171 {
172 /* Swing is not designed to be thread-safe, so there is no
173 * need to synchronize the access to the global variable.
174 */
175 if (blackLineBorder == null)
176 blackLineBorder = new LineBorder(Color.black);
177
178 return blackLineBorder;
179 }
180
181
182 /**
183 * Returns a gray, one pixel thick, plain {@link LineBorder}. The method
184 * may always return the same (singleton) {@link LineBorder} instance.
185 *
186 * @return The border.
187 */
188 public static Border createGrayLineBorder()
189 {
190 /* Swing is not designed to be thread-safe, so there is no
191 * need to synchronize the access to the global variable.
192 */
193 if (grayLineBorder == null)
194 grayLineBorder = new LineBorder(Color.gray);
195
196 return grayLineBorder;
197 }
198
199
200 /**
201 * Paints the line border around a given Component.
202 *
203 * @param c the component whose border is to be painted.
204 * @param g the graphics for painting.
205 * @param x the horizontal position for painting the border.
206 * @param y the vertical position for painting the border.
207 * @param width the width of the available area for painting the border.
208 * @param height the height of the available area for painting the border.
209 */
210 public void paintBorder(Component c, Graphics g,
211 int x, int y, int width, int height)
212 {
213 Color oldColor = g.getColor();
214
215 try
216 {
217 g.setColor(lineColor);
218
219 // If width and height were not adjusted, the border would
220 // appear one pixel too large in both directions.
221 width -= 1;
222 height -= 1;
223
224 // Blurred, too large appearance
225 // -----------------------------
226 // While Java 2D has introduced line strokes of arbitrary width,
227 // it seems desirable to keep this code independent of Java 2D.
228 // Therefore, multiple nested rectangles (or rounded rectangles)
229 // are drawn in order to simulate a line whose thickness is
230 // greater than one pixel.
231 //
232 // This hack causes a blurred appearance when anti-aliasing is
233 // on. Interestingly enough, though, the Sun JDK 1.3.1 (at least
234 // on MacOS X 10.1.5) shows exactly the same appearance under
235 // this condition. It thus seems likely that Sun does the same
236 // hack for simulating thick lines. For this reason, the
237 // blurred appearance seems acceptable -- especially since GNU
238 // Classpath tries to be compatible with the Sun reference
239 // implementation.
240 for (int i = 0; i < thickness; i++)
241 {
242 if (roundedCorners)
243 g.drawRoundRect(x, y, width, height, thickness, thickness);
244 else
245 g.drawRect(x, y, width, height);
246
247 x += 1;
248 y += 1;
249 width -= 2;
250 height -= 2;
251 }
252 }
253 finally
254 {
255 g.setColor(oldColor);
256 }
257 }
258
259
260 /**
261 * Measures the width of this border.
262 *
263 * @param c the component whose border is to be measured.
264 *
265 * @return an Insets object whose <code>left</code>, <code>right</code>,
266 * <code>top</code> and <code>bottom</code> fields indicate the
267 * width of the border at the respective edge, which is the
268 * thickness of the line.
269 *
270 * @see #getBorderInsets(java.awt.Component, java.awt.Insets)
271 */
272 public Insets getBorderInsets(Component c)
273 {
274 return new Insets(thickness, thickness, thickness, thickness);
275 }
276
277
278 /**
279 * Measures the width of this border, storing the results into a
280 * pre-existing Insets object.
281 *
282 * @param insets an Insets object for holding the result values.
283 * After invoking this method, the <code>left</code>,
284 * <code>right</code>, <code>top</code> and
285 * <code>bottom</code> fields indicate the width of the
286 * border at the respective edge, which is the thickness
287 * of the line.
288 *
289 * @return the same object that was passed for <code>insets</code>.
290 *
291 * @see #getBorderInsets(Component)
292 */
293 public Insets getBorderInsets(Component c, Insets insets)
294 {
295 insets.left = insets.right = insets.top = insets.bottom = thickness;
296 return insets;
297 }
298
299
300 /**
301 * Returns the color of the line.
302 *
303 * @return The line color (never <code>null</code>).
304 */
305 public Color getLineColor()
306 {
307 return lineColor;
308 }
309
310
311 /**
312 * Returns the thickness of the line in pixels.
313 *
314 * @return The line thickness (in pixels).
315 */
316 public int getThickness()
317 {
318 return thickness;
319 }
320
321
322 /**
323 * Returns whether this LineBorder os drawm with rounded
324 * or with plain corners.
325 *
326 * @return <code>true</code> if the corners are rounded,
327 * <code>false</code> if the corners are plain.
328 */
329 public boolean getRoundedCorners()
330 {
331 return roundedCorners;
332 }
333
334
335 /**
336 * Determines whether this border fills every pixel in its area
337 * when painting.
338 *
339 * @return <code>true</code> if the corners are plain and the line
340 * color is fully opaque; <code>false</code> if the corners
341 * are rounded or the line color is partially transparent.
342 */
343 public boolean isBorderOpaque()
344 {
345 return (!roundedCorners) && (lineColor.getAlpha() == 255);
346 }
347 }