1 /* 2 * Copyright (c) 1997, 2014, 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 = 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 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 }