View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
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
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
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   *
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.
24   */
25  
26  package java.awt;
27  
28  import java.beans.ConstructorProperties;
29  
30  import java.lang.annotation.Native;
31  
32  /**
33   * The <code>BasicStroke</code> class defines a basic set of rendering
34   * attributes for the outlines of graphics primitives, which are rendered
35   * with a {@link Graphics2D} object that has its Stroke attribute set to
36   * this <code>BasicStroke</code>.
37   * The rendering attributes defined by <code>BasicStroke</code> describe
38   * the shape of the mark made by a pen drawn along the outline of a
39   * {@link Shape} and the decorations applied at the ends and joins of
40   * path segments of the <code>Shape</code>.
41   * These rendering attributes include:
42   * <dl>
43   * <dt><i>width</i>
44   * <dd>The pen width, measured perpendicularly to the pen trajectory.
45   * <dt><i>end caps</i>
46   * <dd>The decoration applied to the ends of unclosed subpaths and
47   * dash segments.  Subpaths that start and end on the same point are
48   * still considered unclosed if they do not have a CLOSE segment.
49   * See {@link java.awt.geom.PathIterator#SEG_CLOSE SEG_CLOSE}
50   * for more information on the CLOSE segment.
51   * The three different decorations are: {@link #CAP_BUTT},
52   * {@link #CAP_ROUND}, and {@link #CAP_SQUARE}.
53   * <dt><i>line joins</i>
54   * <dd>The decoration applied at the intersection of two path segments
55   * and at the intersection of the endpoints of a subpath that is closed
56   * using {@link java.awt.geom.PathIterator#SEG_CLOSE SEG_CLOSE}.
57   * The three different decorations are: {@link #JOIN_BEVEL},
58   * {@link #JOIN_MITER}, and {@link #JOIN_ROUND}.
59   * <dt><i>miter limit</i>
60   * <dd>The limit to trim a line join that has a JOIN_MITER decoration.
61   * A line join is trimmed when the ratio of miter length to stroke
62   * width is greater than the miterlimit value.  The miter length is
63   * the diagonal length of the miter, which is the distance between
64   * the inside corner and the outside corner of the intersection.
65   * The smaller the angle formed by two line segments, the longer
66   * the miter length and the sharper the angle of intersection.  The
67   * default miterlimit value of 10.0f causes all angles less than
68   * 11 degrees to be trimmed.  Trimming miters converts
69   * the decoration of the line join to bevel.
70   * <dt><i>dash attributes</i>
71   * <dd>The definition of how to make a dash pattern by alternating
72   * between opaque and transparent sections.
73   * </dl>
74   * All attributes that specify measurements and distances controlling
75   * the shape of the returned outline are measured in the same
76   * coordinate system as the original unstroked <code>Shape</code>
77   * argument.  When a <code>Graphics2D</code> object uses a
78   * <code>Stroke</code> object to redefine a path during the execution
79   * of one of its <code>draw</code> methods, the geometry is supplied
80   * in its original form before the <code>Graphics2D</code> transform
81   * attribute is applied.  Therefore, attributes such as the pen width
82   * are interpreted in the user space coordinate system of the
83   * <code>Graphics2D</code> object and are subject to the scaling and
84   * shearing effects of the user-space-to-device-space transform in that
85   * particular <code>Graphics2D</code>.
86   * For example, the width of a rendered shape's outline is determined
87   * not only by the width attribute of this <code>BasicStroke</code>,
88   * but also by the transform attribute of the
89   * <code>Graphics2D</code> object.  Consider this code:
90   * <blockquote><tt>
91   *      // sets the Graphics2D object's Transform attribute
92   *      g2d.scale(10, 10);
93   *      // sets the Graphics2D object's Stroke attribute
94   *      g2d.setStroke(new BasicStroke(1.5f));
95   * </tt></blockquote>
96   * Assuming there are no other scaling transforms added to the
97   * <code>Graphics2D</code> object, the resulting line
98   * will be approximately 15 pixels wide.
99   * As the example code demonstrates, a floating-point line
100  * offers better precision, especially when large transforms are
101  * used with a <code>Graphics2D</code> object.
102  * When a line is diagonal, the exact width depends on how the
103  * rendering pipeline chooses which pixels to fill as it traces the
104  * theoretical widened outline.  The choice of which pixels to turn
105  * on is affected by the antialiasing attribute because the
106  * antialiasing rendering pipeline can choose to color
107  * partially-covered pixels.
108  * <p>
109  * For more information on the user space coordinate system and the
110  * rendering process, see the <code>Graphics2D</code> class comments.
111  * @see Graphics2D
112  * @author Jim Graham
113  */
114 public class BasicStroke implements Stroke {
115 
116     /**
117      * Joins path segments by extending their outside edges until
118      * they meet.
119      */
120     @Native public final static int JOIN_MITER = 0;
121 
122     /**
123      * Joins path segments by rounding off the corner at a radius
124      * of half the line width.
125      */
126     @Native public final static int JOIN_ROUND = 1;
127 
128     /**
129      * Joins path segments by connecting the outer corners of their
130      * wide outlines with a straight segment.
131      */
132     @Native public final static int JOIN_BEVEL = 2;
133 
134     /**
135      * Ends unclosed subpaths and dash segments with no added
136      * decoration.
137      */
138     @Native public final static int CAP_BUTT = 0;
139 
140     /**
141      * Ends unclosed subpaths and dash segments with a round
142      * decoration that has a radius equal to half of the width
143      * of the pen.
144      */
145     @Native public final static int CAP_ROUND = 1;
146 
147     /**
148      * Ends unclosed subpaths and dash segments with a square
149      * projection that extends beyond the end of the segment
150      * to a distance equal to half of the line width.
151      */
152     @Native public final static int CAP_SQUARE = 2;
153 
154     float width;
155 
156     int join;
157     int cap;
158     float miterlimit;
159 
160     float dash[];
161     float dash_phase;
162 
163     /**
164      * Constructs a new <code>BasicStroke</code> with the specified
165      * attributes.
166      * @param width the width of this <code>BasicStroke</code>.  The
167      *         width must be greater than or equal to 0.0f.  If width is
168      *         set to 0.0f, the stroke is rendered as the thinnest
169      *         possible line for the target device and the antialias
170      *         hint setting.
171      * @param cap the decoration of the ends of a <code>BasicStroke</code>
172      * @param join the decoration applied where path segments meet
173      * @param miterlimit the limit to trim the miter join.  The miterlimit
174      *        must be greater than or equal to 1.0f.
175      * @param dash the array representing the dashing pattern
176      * @param dash_phase the offset to start the dashing pattern
177      * @throws IllegalArgumentException if <code>width</code> is negative
178      * @throws IllegalArgumentException if <code>cap</code> is not either
179      *         CAP_BUTT, CAP_ROUND or CAP_SQUARE
180      * @throws IllegalArgumentException if <code>miterlimit</code> is less
181      *         than 1 and <code>join</code> is JOIN_MITER
182      * @throws IllegalArgumentException if <code>join</code> is not
183      *         either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER
184      * @throws IllegalArgumentException if <code>dash_phase</code>
185      *         is negative and <code>dash</code> is not <code>null</code>
186      * @throws IllegalArgumentException if the length of
187      *         <code>dash</code> is zero
188      * @throws IllegalArgumentException if dash lengths are all zero.
189      */
190     @ConstructorProperties({ "lineWidth", "endCap", "lineJoin", "miterLimit", "dashArray", "dashPhase" })
191     public BasicStroke(float width, int cap, int join, float miterlimit,
192                        float dash[], float dash_phase) {
193         if (width < 0.0f) {
194             throw new IllegalArgumentException("negative width");
195         }
196         if (cap != CAP_BUTT && cap != CAP_ROUND && cap != CAP_SQUARE) {
197             throw new IllegalArgumentException("illegal end cap value");
198         }
199         if (join == JOIN_MITER) {
200             if (miterlimit < 1.0f) {
201                 throw new IllegalArgumentException("miter limit < 1");
202             }
203         } else if (join != JOIN_ROUND && join != JOIN_BEVEL) {
204             throw new IllegalArgumentException("illegal line join value");
205         }
206         if (dash != null) {
207             if (dash_phase < 0.0f) {
208                 throw new IllegalArgumentException("negative dash phase");
209             }
210             boolean allzero = true;
211             for (int i = 0; i < dash.length; i++) {
212                 float d = dash[i];
213                 if (d > 0.0) {
214                     allzero = false;
215                 } else if (d < 0.0) {
216                     throw new IllegalArgumentException("negative dash length");
217                 }
218             }
219             if (allzero) {
220                 throw new IllegalArgumentException("dash lengths all zero");
221             }
222         }
223         this.width      = width;
224         this.cap        = cap;
225         this.join       = join;
226         this.miterlimit = miterlimit;
227         if (dash != null) {
228             this.dash = (float []) dash.clone();
229         }
230         this.dash_phase = dash_phase;
231     }
232 
233     /**
234      * Constructs a solid <code>BasicStroke</code> with the specified
235      * attributes.
236      * @param width the width of the <code>BasicStroke</code>
237      * @param cap the decoration of the ends of a <code>BasicStroke</code>
238      * @param join the decoration applied where path segments meet
239      * @param miterlimit the limit to trim the miter join
240      * @throws IllegalArgumentException if <code>width</code> is negative
241      * @throws IllegalArgumentException if <code>cap</code> is not either
242      *         CAP_BUTT, CAP_ROUND or CAP_SQUARE
243      * @throws IllegalArgumentException if <code>miterlimit</code> is less
244      *         than 1 and <code>join</code> is JOIN_MITER
245      * @throws IllegalArgumentException if <code>join</code> is not
246      *         either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER
247      */
248     public BasicStroke(float width, int cap, int join, float miterlimit) {
249         this(width, cap, join, miterlimit, null, 0.0f);
250     }
251 
252     /**
253      * Constructs a solid <code>BasicStroke</code> with the specified
254      * attributes.  The <code>miterlimit</code> parameter is
255      * unnecessary in cases where the default is allowable or the
256      * line joins are not specified as JOIN_MITER.
257      * @param width the width of the <code>BasicStroke</code>
258      * @param cap the decoration of the ends of a <code>BasicStroke</code>
259      * @param join the decoration applied where path segments meet
260      * @throws IllegalArgumentException if <code>width</code> is negative
261      * @throws IllegalArgumentException if <code>cap</code> is not either
262      *         CAP_BUTT, CAP_ROUND or CAP_SQUARE
263      * @throws IllegalArgumentException if <code>join</code> is not
264      *         either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER
265      */
266     public BasicStroke(float width, int cap, int join) {
267         this(width, cap, join, 10.0f, null, 0.0f);
268     }
269 
270     /**
271      * Constructs a solid <code>BasicStroke</code> with the specified
272      * line width and with default values for the cap and join
273      * styles.
274      * @param width the width of the <code>BasicStroke</code>
275      * @throws IllegalArgumentException if <code>width</code> is negative
276      */
277     public BasicStroke(float width) {
278         this(width, CAP_SQUARE, JOIN_MITER, 10.0f, null, 0.0f);
279     }
280 
281     /**
282      * Constructs a new <code>BasicStroke</code> with defaults for all
283      * attributes.
284      * The default attributes are a solid line of width 1.0, CAP_SQUARE,
285      * JOIN_MITER, a miter limit of 10.0.
286      */
287     public BasicStroke() {
288         this(1.0f, CAP_SQUARE, JOIN_MITER, 10.0f, null, 0.0f);
289     }
290 
291 
292     /**
293      * Returns a <code>Shape</code> whose interior defines the
294      * stroked outline of a specified <code>Shape</code>.
295      * @param s the <code>Shape</code> boundary be stroked
296      * @return the <code>Shape</code> of the stroked outline.
297      */
298     public Shape createStrokedShape(Shape s) {
299         sun.java2d.pipe.RenderingEngine re =
300             sun.java2d.pipe.RenderingEngine.getInstance();
301         return re.createStrokedShape(s, width, cap, join, miterlimit,
302                                      dash, dash_phase);
303     }
304 
305     /**
306      * Returns the line width.  Line width is represented in user space,
307      * which is the default-coordinate space used by Java 2D.  See the
308      * <code>Graphics2D</code> class comments for more information on
309      * the user space coordinate system.
310      * @return the line width of this <code>BasicStroke</code>.
311      * @see Graphics2D
312      */
313     public float getLineWidth() {
314         return width;
315     }
316 
317     /**
318      * Returns the end cap style.
319      * @return the end cap style of this <code>BasicStroke</code> as one
320      * of the static <code>int</code> values that define possible end cap
321      * styles.
322      */
323     public int getEndCap() {
324         return cap;
325     }
326 
327     /**
328      * Returns the line join style.
329      * @return the line join style of the <code>BasicStroke</code> as one
330      * of the static <code>int</code> values that define possible line
331      * join styles.
332      */
333     public int getLineJoin() {
334         return join;
335     }
336 
337     /**
338      * Returns the limit of miter joins.
339      * @return the limit of miter joins of the <code>BasicStroke</code>.
340      */
341     public float getMiterLimit() {
342         return miterlimit;
343     }
344 
345     /**
346      * Returns the array representing the lengths of the dash segments.
347      * Alternate entries in the array represent the user space lengths
348      * of the opaque and transparent segments of the dashes.
349      * As the pen moves along the outline of the <code>Shape</code>
350      * to be stroked, the user space
351      * distance that the pen travels is accumulated.  The distance
352      * value is used to index into the dash array.
353      * The pen is opaque when its current cumulative distance maps
354      * to an even element of the dash array and transparent otherwise.
355      * @return the dash array.
356      */
357     public float[] getDashArray() {
358         if (dash == null) {
359             return null;
360         }
361 
362         return (float[]) dash.clone();
363     }
364 
365     /**
366      * Returns the current dash phase.
367      * The dash phase is a distance specified in user coordinates that
368      * represents an offset into the dashing pattern. In other words, the dash
369      * phase defines the point in the dashing pattern that will correspond to
370      * the beginning of the stroke.
371      * @return the dash phase as a <code>float</code> value.
372      */
373     public float getDashPhase() {
374         return dash_phase;
375     }
376 
377     /**
378      * Returns the hashcode for this stroke.
379      * @return      a hash code for this stroke.
380      */
381     public int hashCode() {
382         int hash = Float.floatToIntBits(width);
383         hash = hash * 31 + join;
384         hash = hash * 31 + cap;
385         hash = hash * 31 + Float.floatToIntBits(miterlimit);
386         if (dash != null) {
387             hash = hash * 31 + Float.floatToIntBits(dash_phase);
388             for (int i = 0; i < dash.length; i++) {
389                 hash = hash * 31 + Float.floatToIntBits(dash[i]);
390             }
391         }
392         return hash;
393     }
394 
395     /**
396      * Returns true if this BasicStroke represents the same
397      * stroking operation as the given argument.
398      */
399    /**
400     * Tests if a specified object is equal to this <code>BasicStroke</code>
401     * by first testing if it is a <code>BasicStroke</code> and then comparing
402     * its width, join, cap, miter limit, dash, and dash phase attributes with
403     * those of this <code>BasicStroke</code>.
404     * @param  obj the specified object to compare to this
405     *              <code>BasicStroke</code>
406     * @return <code>true</code> if the width, join, cap, miter limit, dash, and
407     *            dash phase are the same for both objects;
408     *            <code>false</code> otherwise.
409     */
410     public boolean equals(Object obj) {
411         if (!(obj instanceof BasicStroke)) {
412             return false;
413         }
414 
415         BasicStroke bs = (BasicStroke) obj;
416         if (width != bs.width) {
417             return false;
418         }
419 
420         if (join != bs.join) {
421             return false;
422         }
423 
424         if (cap != bs.cap) {
425             return false;
426         }
427 
428         if (miterlimit != bs.miterlimit) {
429             return false;
430         }
431 
432         if (dash != null) {
433             if (dash_phase != bs.dash_phase) {
434                 return false;
435             }
436 
437             if (!java.util.Arrays.equals(dash, bs.dash)) {
438                 return false;
439             }
440         }
441         else if (bs.dash != null) {
442             return false;
443         }
444 
445         return true;
446     }
447 }