OpenJDK 27 · java.awt.BasicStroke · APIdia, the JavaDoc alternative

The BasicStroke class defines a basic set of rendering attributes for the outlines of graphics primitives, which are rendered with a 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 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 SEG_CLOSE for more information on the CLOSE segment. The three different decorations are: CAP_BUTT, CAP_ROUND, and 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 SEG_CLOSE. The three different decorations are: JOIN_BEVEL, JOIN_MITER, and 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 Transform 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.

Field Summary

Modifier and Type	Field and Description
pack-priv int	cap
public static final int	CAP_BUTT Ends unclosed subpaths and dash segments with no added decoration.
public static final int	CAP_ROUND Ends unclosed subpaths and dash segments with a round decoration that has a radius equal to half of the width of the pen.
public static final int	CAP_SQUARE 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.
pack-priv float[]	dash
pack-priv float	dash_phase
pack-priv int	join
public static final int	JOIN_BEVEL Joins path segments by connecting the outer corners of their wide outlines with a straight segment.
public static final int	JOIN_MITER Joins path segments by extending their outside edges until they meet.
public static final int	JOIN_ROUND Joins path segments by rounding off the corner at a radius of half the line width.
pack-priv float	miterlimit
pack-priv float	width

Constructor Summary

Access	Constructor and Description
public	BasicStroke(float 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. width, int the decoration of the ends of a `BasicStroke` cap, int the decoration applied where path segments meet join, float the limit to trim the miter join. The miterlimit must be greater than or equal to 1.0f. miterlimit, float[] the array representing the dashing pattern dash, float the offset to start the dashing pattern dash_phase) Constructs a new `BasicStroke` with the specified attributes.
public	BasicStroke(float the width of the `BasicStroke` width, int the decoration of the ends of a `BasicStroke` cap, int the decoration applied where path segments meet join, float the limit to trim the miter join miterlimit) Constructs a solid `BasicStroke` with the specified attributes.
public	BasicStroke(float the width of the `BasicStroke` width, int the decoration of the ends of a `BasicStroke` cap, int the decoration applied where path segments meet join) Constructs a solid `BasicStroke` with the specified attributes.
public	BasicStroke(float the width of the `BasicStroke` width) Constructs a solid `BasicStroke` with the specified line width and with default values for the cap and join styles.
public	BasicStroke() Constructs a new `BasicStroke` with defaults for all attributes.

Method Summary

Modifier and Type	Method and Description
public Shape	Returns: the `Shape` of the stroked outline. createStrokedShape(Shape the `Shape` boundary be stroked s) Implements java.awt.Stroke.createStrokedShape. Returns a `Shape` whose interior defines the stroked outline of a specified `Shape`.
public boolean	Returns: `true` if the width, join, cap, miter limit, dash, and dash phase are the same for both objects; `false` otherwise. equals(Object the specified object to compare to this `BasicStroke` obj) Overrides java.lang.Object.equals. 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`.
public float[]	Returns: the dash array. getDashArray() Returns the array representing the lengths of the dash segments.
public float	Returns: the dash phase as a `float` value. getDashPhase() Returns the current dash phase.
public int	Returns: the end cap style of this `BasicStroke` as one of the static `int` values that define possible end cap styles. getEndCap() Returns the end cap style.
public int	Returns: the line join style of the `BasicStroke` as one of the static `int` values that define possible line join styles. getLineJoin() Returns the line join style.
public float	Returns: the line width of this `BasicStroke`. getLineWidth() Returns the line width.
public float	Returns: the limit of miter joins of the `BasicStroke`. getMiterLimit() Returns the limit of miter joins.
public int	Returns: a hash code for this stroke. hashCode() Overrides java.lang.Object.hashCode. Returns the hashcode for this stroke.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll toString wait wait wait

Field Detail

cap	back to summary
pack-priv int cap

CAP_BUTT	back to summary
public static final int CAP_BUTT Ends unclosed subpaths and dash segments with no added decoration. Annotations @Native

CAP_ROUND	back to summary
public static final int CAP_ROUND Ends unclosed subpaths and dash segments with a round decoration that has a radius equal to half of the width of the pen. Annotations @Native

CAP_SQUARE	back to summary
public static final int CAP_SQUARE 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. Annotations @Native

dash	back to summary
pack-priv float[] dash

dash_phase	back to summary
pack-priv float dash_phase

join	back to summary
pack-priv int join

JOIN_BEVEL	back to summary
public static final int JOIN_BEVEL Joins path segments by connecting the outer corners of their wide outlines with a straight segment. Annotations @Native

JOIN_MITER	back to summary
public static final int JOIN_MITER Joins path segments by extending their outside edges until they meet. Annotations @Native

JOIN_ROUND	back to summary
public static final int JOIN_ROUND Joins path segments by rounding off the corner at a radius of half the line width. Annotations @Native

miterlimit	back to summary
pack-priv float miterlimit

width	back to summary
pack-priv float width

Constructor Detail

BasicStroke back to summary

BasicStroke	back to summary
public BasicStroke(float width, int cap, int join, float miterlimit, float[] dash, float dash_phase) Constructs a new `BasicStroke` with the specified attributes. Parameters width:float 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. cap:int the decoration of the ends of a `BasicStroke` join:int the decoration applied where path segments meet miterlimit:float the limit to trim the miter join. The miterlimit must be greater than or equal to 1.0f. dash:float[] the array representing the dashing pattern dash_phase:float the offset to start the dashing pattern Annotations @ConstructorProperties:lineWidth, endCap, lineJoin, miterLimit, dashArray, dashPhase Exceptions IllegalArgumentException: if `width` is negative if `cap` is not either CAP_BUTT, CAP_ROUND or CAP_SQUARE if `miterlimit` is less than 1 and `join` is JOIN_MITER if `join` is not either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER if `dash_phase` is negative and `dash` is not `null` if the length of `dash` is zero if dash lengths are all zero.

public BasicStroke(float width, int cap, int join, float miterlimit, float[] dash, float dash_phase)

Constructs a new BasicStroke with the specified attributes.

Parameters

width:float: 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.
cap:int: the decoration of the ends of a BasicStroke
join:int: the decoration applied where path segments meet
miterlimit:float: the limit to trim the miter join. The miterlimit must be greater than or equal to 1.0f.
dash:float[]: the array representing the dashing pattern
dash_phase:float: the offset to start the dashing pattern

Annotations

@ConstructorProperties:lineWidth, endCap, lineJoin, miterLimit, dashArray, dashPhase

Exceptions

IllegalArgumentException:

if width is negative
if cap is not either CAP_BUTT, CAP_ROUND or CAP_SQUARE
if miterlimit is less than 1 and join is JOIN_MITER
if join is not either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER
if dash_phase is negative and dash is not null
if the length of dash is zero
if dash lengths are all zero.

BasicStroke back to summary

BasicStroke	back to summary
public BasicStroke(float width, int cap, int join, float miterlimit) Constructs a solid `BasicStroke` with the specified attributes. Parameters width:float the width of the `BasicStroke` cap:int the decoration of the ends of a `BasicStroke` join:int the decoration applied where path segments meet miterlimit:float the limit to trim the miter join Exceptions IllegalArgumentException: if `width` is negative if `cap` is not either CAP_BUTT, CAP_ROUND or CAP_SQUARE if `miterlimit` is less than 1 and `join` is JOIN_MITER if `join` is not either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER

public BasicStroke(float width, int cap, int join, float miterlimit)

Constructs a solid BasicStroke with the specified attributes.

Parameters

width:float: the width of the BasicStroke
cap:int: the decoration of the ends of a BasicStroke
join:int: the decoration applied where path segments meet
miterlimit:float: the limit to trim the miter join

Exceptions

IllegalArgumentException:

if width is negative
if cap is not either CAP_BUTT, CAP_ROUND or CAP_SQUARE
if miterlimit is less than 1 and join is JOIN_MITER
if join is not either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER

BasicStroke back to summary

BasicStroke	back to summary
public BasicStroke(float width, int cap, int join) 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. Parameters width:float the width of the `BasicStroke` cap:int the decoration of the ends of a `BasicStroke` join:int the decoration applied where path segments meet Exceptions IllegalArgumentException: if `width` is negative if `cap` is not either CAP_BUTT, CAP_ROUND or CAP_SQUARE if `join` is not either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER

public BasicStroke(float width, int cap, int join)

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.

Parameters

width:float: the width of the BasicStroke
cap:int: the decoration of the ends of a BasicStroke
join:int: the decoration applied where path segments meet

Exceptions

IllegalArgumentException:

if width is negative
if cap is not either CAP_BUTT, CAP_ROUND or CAP_SQUARE
if join is not either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER

BasicStroke back to summary

BasicStroke	back to summary
public BasicStroke(float width) Constructs a solid `BasicStroke` with the specified line width and with default values for the cap and join styles. Parameters width:float the width of the `BasicStroke` Exceptions IllegalArgumentException: if `width` is negative

public BasicStroke(float width)

Constructs a solid BasicStroke with the specified line width and with default values for the cap and join styles.

Parameters

width:float: the width of the BasicStroke

Exceptions

IllegalArgumentException:: if width is negative

BasicStroke	back to summary
public BasicStroke() 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.

Method Detail

createStrokedShape back to summary

createStrokedShape	back to summary
public Shape createStrokedShape(Shape s) Implements java.awt.Stroke.createStrokedShape. Returns a `Shape` whose interior defines the stroked outline of a specified `Shape`. Parameters s:Shape the `Shape` boundary be stroked Returns:Shape the `Shape` of the stroked outline. Exceptions NullPointerException: if `s` is `null`

public Shape createStrokedShape(Shape s)

Implements java.awt.Stroke.createStrokedShape.

Returns a Shape whose interior defines the stroked outline of a specified Shape.

Parameters

s:Shape: the Shape boundary be stroked

Returns:Shape

the Shape of the stroked outline.

Exceptions

NullPointerException:: if s is null

equals back to summary

equals	back to summary
public boolean equals(Object obj) Overrides java.lang.Object.equals. 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`. Parameters obj:Object the specified object to compare to this `BasicStroke` Returns:boolean `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)

Overrides java.lang.Object.equals.

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.

Parameters

obj:Object: the specified object to compare to this BasicStroke

Returns:boolean

true if the width, join, cap, miter limit, dash, and dash phase are the same for both objects; false otherwise.

getDashArray back to summary

getDashArray	back to summary
public float[] getDashArray() 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. Returns:float[] the dash array.

public float[] getDashArray()

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.

Returns:float[]: the dash array.

getDashPhase back to summary

getDashPhase	back to summary
public float getDashPhase() 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. Returns:float the dash phase as a `float` value.

public float getDashPhase()

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.

Returns:float: the dash phase as a float value.

getEndCap back to summary

getEndCap	back to summary
public int getEndCap() Returns the end cap style. Returns:int the end cap style of this `BasicStroke` as one of the static `int` values that define possible end cap styles.

public int getEndCap()

Returns the end cap style.

Returns:int: the end cap style of this BasicStroke as one of the static int values that define possible end cap styles.

getLineJoin back to summary

getLineJoin	back to summary
public int getLineJoin() Returns the line join style. Returns:int the line join style of the `BasicStroke` as one of the static `int` values that define possible line join styles.

public int getLineJoin()

Returns the line join style.

Returns:int: the line join style of the BasicStroke as one of the static int values that define possible line join styles.

getLineWidth back to summary

getLineWidth	back to summary
public float getLineWidth() 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. Returns:float the line width of this `BasicStroke`. See Also `Graphics2D`

public float getLineWidth()

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.

Returns:float: the line width of this BasicStroke.
See Also: Graphics2D

getMiterLimit back to summary

getMiterLimit	back to summary
public float getMiterLimit() Returns the limit of miter joins. Returns:float the limit of miter joins of the `BasicStroke`.

public float getMiterLimit()

Returns the limit of miter joins.

Returns:float: the limit of miter joins of the BasicStroke.

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Returns the hashcode for this stroke. Returns:int a hash code for this stroke.

hashCode

back to summary

public int hashCode()

Overrides java.lang.Object.hashCode.

Returns the hashcode for this stroke.

Returns:int: a hash code for this stroke.

public Class BasicStroke

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail