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    }