com.levigo.util.gwtawt.emul.java.awt.BasicStroke Maven / Gradle / Ivy
Show all versions of gwt-awt Show documentation
/*
* Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved. DO NOT ALTER OR
* REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it under the terms of the GNU
* General Public License version 2 only, as published by the Free Software Foundation. Oracle
* designates this particular file as subject to the "Classpath" exception as provided by Oracle in
* the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
* even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version 2 along with this work;
* if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA or visit www.oracle.com
* if you need additional information or have any questions.
*/
package java.awt;
import com.levigo.util.gwtawt.client.helper.Cloner;
/**
* The BasicStroke class defines a basic set of rendering attributes for the outlines
* of graphics primitives, which are rendered with a {@link Graphics2D} object that has its Stroke
* attribute set to this BasicStroke. The rendering attributes defined by
* BasicStroke describe the shape of the mark made by a pen drawn along the outline of
* a {@link Shape} and the decorations applied at the ends and joins of path segments of the
* Shape. These rendering attributes include:
*
* - width
*
- The pen width, measured perpendicularly to the pen trajectory.
*
- end caps
*
- The decoration applied to the ends of unclosed subpaths and dash segments. Subpaths that
* start and end on the same point are still considered unclosed if they do not have a CLOSE
* segment. See {@link java.awt.geom.PathIterator#SEG_CLOSE SEG_CLOSE} for more information on the
* CLOSE segment. The three different decorations are: {@link #CAP_BUTT}, {@link #CAP_ROUND}, and
* {@link #CAP_SQUARE}.
*
- line joins
*
- The decoration applied at the intersection of two path segments and at the intersection of
* the endpoints of a subpath that is closed using {@link java.awt.geom.PathIterator#SEG_CLOSE
* SEG_CLOSE}. The three different decorations are: {@link #JOIN_BEVEL}, {@link #JOIN_MITER}, and
* {@link #JOIN_ROUND}.
*
- miter limit
*
- The limit to trim a line join that has a JOIN_MITER decoration. A line join is trimmed when
* the ratio of miter length to stroke width is greater than the miterlimit value. The miter length
* is the diagonal length of the miter, which is the distance between the inside corner and the
* outside corner of the intersection. The smaller the angle formed by two line segments, the longer
* the miter length and the sharper the angle of intersection. The default miterlimit value of 10.0f
* causes all angles less than 11 degrees to be trimmed. Trimming miters converts the decoration of
* the line join to bevel.
*
- dash attributes
*
- The definition of how to make a dash pattern by alternating between opaque and transparent
* sections.
*
* All attributes that specify measurements and distances controlling the shape of the returned
* outline are measured in the same coordinate system as the original unstroked Shape
* argument. When a Graphics2D object uses a Stroke object to redefine a
* path during the execution of one of its draw methods, the geometry is supplied in
* its original form before the Graphics2D transform attribute is applied. Therefore,
* attributes such as the pen width are interpreted in the user space coordinate system of the
* Graphics2D object and are subject to the scaling and shearing effects of the
* user-space-to-device-space transform in that particular Graphics2D. For example, the
* width of a rendered shape's outline is determined not only by the width attribute of this
* BasicStroke, but also by the transform attribute of the Graphics2D
* object. Consider this code:
* // sets the Graphics2D object's Tranform attribute
* g2d.scale(10, 10);
* // sets the Graphics2D object's Stroke attribute
* g2d.setStroke(new BasicStroke(1.5f));
*
Assuming there are no other scaling transforms added to the
* Graphics2D object, the resulting line will be approximately 15 pixels wide. As the
* example code demonstrates, a floating-point line offers better precision, especially when large
* transforms are used with a Graphics2D object. When a line is diagonal, the exact
* width depends on how the rendering pipeline chooses which pixels to fill as it traces the
* theoretical widened outline. The choice of which pixels to turn on is affected by the
* antialiasing attribute because the antialiasing rendering pipeline can choose to color
* partially-covered pixels.
*
* For more information on the user space coordinate system and the rendering process, see the
* Graphics2D class comments.
*
* @see Graphics2D
* @author Jim Graham
*/
public class BasicStroke implements Stroke {
/**
* Joins path segments by extending their outside edges until they meet.
*/
public final static int JOIN_MITER = 0;
/**
* Joins path segments by rounding off the corner at a radius of half the line width.
*/
public final static int JOIN_ROUND = 1;
/**
* Joins path segments by connecting the outer corners of their wide outlines with a straight
* segment.
*/
public final static int JOIN_BEVEL = 2;
/**
* Ends unclosed subpaths and dash segments with no added decoration.
*/
public final static int CAP_BUTT = 0;
/**
* Ends unclosed subpaths and dash segments with a round decoration that has a radius equal to
* half of the width of the pen.
*/
public final static int CAP_ROUND = 1;
/**
* Ends unclosed subpaths and dash segments with a square projection that extends beyond the end
* of the segment to a distance equal to half of the line width.
*/
public final static int CAP_SQUARE = 2;
float width;
int join;
int cap;
float miterlimit;
float dash[];
float dash_phase;
/**
* Constructs a new BasicStroke with the specified attributes.
*
* @param width the width of this BasicStroke. The width must be greater than or
* equal to 0.0f. If width is set to 0.0f, the stroke is rendered as the thinnest
* possible line for the target device and the antialias hint setting.
* @param cap the decoration of the ends of a BasicStroke
* @param join the decoration applied where path segments meet
* @param miterlimit the limit to trim the miter join. The miterlimit must be greater than or
* equal to 1.0f.
* @param dash the array representing the dashing pattern
* @param dash_phase the offset to start the dashing pattern
* @throws IllegalArgumentException if width is negative
* @throws IllegalArgumentException if cap is not either CAP_BUTT, CAP_ROUND or
* CAP_SQUARE
* @throws IllegalArgumentException if miterlimit is less than 1 and
* join is JOIN_MITER
* @throws IllegalArgumentException if join is not either JOIN_ROUND, JOIN_BEVEL, or
* JOIN_MITER
* @throws IllegalArgumentException if dash_phase is negative and dash
* is not null
* @throws IllegalArgumentException if the length of dash is zero
* @throws IllegalArgumentException if dash lengths are all zero.
*/
// @ConstructorProperties({
// "lineWidth", "endCap", "lineJoin", "miterLimit", "dashArray", "dashPhase"
// })
public BasicStroke(float width, int cap, int join, float miterlimit, float dash[], float dash_phase) {
if (width < 0.0f) {
throw new IllegalArgumentException("negative width");
}
if (cap != CAP_BUTT && cap != CAP_ROUND && cap != CAP_SQUARE) {
throw new IllegalArgumentException("illegal end cap value");
}
if (join == JOIN_MITER) {
if (miterlimit < 1.0f) {
throw new IllegalArgumentException("miter limit < 1");
}
} else if (join != JOIN_ROUND && join != JOIN_BEVEL) {
throw new IllegalArgumentException("illegal line join value");
}
if (dash != null) {
if (dash_phase < 0.0f) {
throw new IllegalArgumentException("negative dash phase");
}
boolean allzero = true;
for (int i = 0; i < dash.length; i++) {
float d = dash[i];
if (d > 0.0) {
allzero = false;
} else if (d < 0.0) {
throw new IllegalArgumentException("negative dash length");
}
}
if (allzero) {
throw new IllegalArgumentException("dash lengths all zero");
}
}
this.width = width;
this.cap = cap;
this.join = join;
this.miterlimit = miterlimit;
if (dash != null) {
this.dash = Cloner.clone(dash);
}
this.dash_phase = dash_phase;
}
/**
* Constructs a solid BasicStroke with the specified attributes.
*
* @param width the width of the BasicStroke
* @param cap the decoration of the ends of a BasicStroke
* @param join the decoration applied where path segments meet
* @param miterlimit the limit to trim the miter join
* @throws IllegalArgumentException if width is negative
* @throws IllegalArgumentException if cap is not either CAP_BUTT, CAP_ROUND or
* CAP_SQUARE
* @throws IllegalArgumentException if miterlimit is less than 1 and
* join is JOIN_MITER
* @throws IllegalArgumentException if join is not either JOIN_ROUND, JOIN_BEVEL, or
* JOIN_MITER
*/
public BasicStroke(float width, int cap, int join, float miterlimit) {
this(width, cap, join, miterlimit, null, 0.0f);
}
/**
* Constructs a solid BasicStroke with the specified attributes. The
* miterlimit parameter is unnecessary in cases where the default is allowable or the
* line joins are not specified as JOIN_MITER.
*
* @param width the width of the BasicStroke
* @param cap the decoration of the ends of a BasicStroke
* @param join the decoration applied where path segments meet
* @throws IllegalArgumentException if width is negative
* @throws IllegalArgumentException if cap is not either CAP_BUTT, CAP_ROUND or
* CAP_SQUARE
* @throws IllegalArgumentException if join is not either JOIN_ROUND, JOIN_BEVEL, or
* JOIN_MITER
*/
public BasicStroke(float width, int cap, int join) {
this(width, cap, join, 10.0f, null, 0.0f);
}
/**
* Constructs a solid BasicStroke with the specified line width and with default
* values for the cap and join styles.
*
* @param width the width of the BasicStroke
* @throws IllegalArgumentException if width is negative
*/
public BasicStroke(float width) {
this(width, CAP_SQUARE, JOIN_MITER, 10.0f, null, 0.0f);
}
/**
* Constructs a new BasicStroke with defaults for all attributes. The default
* attributes are a solid line of width 1.0, CAP_SQUARE, JOIN_MITER, a miter limit of 10.0.
*/
public BasicStroke() {
this(1.0f, CAP_SQUARE, JOIN_MITER, 10.0f, null, 0.0f);
}
/**
* Returns a Shape whose interior defines the stroked outline of a specified
* Shape.
*
* @param s the Shape boundary be stroked
* @return the Shape of the stroked outline.
*/
public Shape createStrokedShape(Shape s) {
// TODO not implemented
assert (false) : "Not implemented yet";
return null;
// sun.java2d.pipe.RenderingEngine re = sun.java2d.pipe.RenderingEngine.getInstance();
// return re.createStrokedShape(s, width, cap, join, miterlimit, dash, dash_phase);
}
/**
* Returns the line width. Line width is represented in user space, which is the
* default-coordinate space used by Java 2D. See the Graphics2D class comments for
* more information on the user space coordinate system.
*
* @return the line width of this BasicStroke.
* @see Graphics2D
*/
public float getLineWidth() {
return width;
}
/**
* Returns the end cap style.
*
* @return the end cap style of this BasicStroke as one of the static
* int values that define possible end cap styles.
*/
public int getEndCap() {
return cap;
}
/**
* Returns the line join style.
*
* @return the line join style of the BasicStroke as one of the static
* int values that define possible line join styles.
*/
public int getLineJoin() {
return join;
}
/**
* Returns the limit of miter joins.
*
* @return the limit of miter joins of the BasicStroke.
*/
public float getMiterLimit() {
return miterlimit;
}
/**
* Returns the array representing the lengths of the dash segments. Alternate entries in the array
* represent the user space lengths of the opaque and transparent segments of the dashes. As the
* pen moves along the outline of the Shape to be stroked, the user space distance
* that the pen travels is accumulated. The distance value is used to index into the dash array.
* The pen is opaque when its current cumulative distance maps to an even element of the dash
* array and transparent otherwise.
*
* @return the dash array.
*/
public float[] getDashArray() {
if (dash == null) {
return null;
}
return Cloner.clone(dash);
}
/**
* Returns the current dash phase. The dash phase is a distance specified in user coordinates that
* represents an offset into the dashing pattern. In other words, the dash phase defines the point
* in the dashing pattern that will correspond to the beginning of the stroke.
*
* @return the dash phase as a float value.
*/
public float getDashPhase() {
return dash_phase;
}
/**
* Returns the hashcode for this stroke.
*
* @return a hash code for this stroke.
*/
public int hashCode() {
int hash = Float.floatToIntBits(width);
hash = hash * 31 + join;
hash = hash * 31 + cap;
hash = hash * 31 + Float.floatToIntBits(miterlimit);
if (dash != null) {
hash = hash * 31 + Float.floatToIntBits(dash_phase);
for (int i = 0; i < dash.length; i++) {
hash = hash * 31 + Float.floatToIntBits(dash[i]);
}
}
return hash;
}
/**
* Returns true if this BasicStroke represents the same stroking operation as the given argument.
*/
/**
* Tests if a specified object is equal to this BasicStroke by first testing if it is
* a BasicStroke and then comparing its width, join, cap, miter limit, dash, and dash
* phase attributes with those of this BasicStroke.
*
* @param obj the specified object to compare to this BasicStroke
* @return true if the width, join, cap, miter limit, dash, and dash phase are the
* same for both objects; false otherwise.
*/
public boolean equals(Object obj) {
if (!(obj instanceof BasicStroke)) {
return false;
}
BasicStroke bs = (BasicStroke) obj;
if (width != bs.width) {
return false;
}
if (join != bs.join) {
return false;
}
if (cap != bs.cap) {
return false;
}
if (miterlimit != bs.miterlimit) {
return false;
}
if (dash != null) {
if (dash_phase != bs.dash_phase) {
return false;
}
if (!java.util.Arrays.equals(dash, bs.dash)) {
return false;
}
} else if (bs.dash != null) {
return false;
}
return true;
}
}