ImageSetDrawingStroke

Sets the stroke properties for subsequent drawing operations on an image.

Syntax

ImageSetDrawingStroke( name [, attributeCollection] )

Or as a member:

someImage.setDrawingStroke( [attributeCollection] )

Arguments

Name	Type	Required	Description
name	any	Yes	The image to set the drawing stroke for. Can be a BoxImage object or image name.
attributeCollection	struct	No	A struct of stroke attributes. See below for supported keys.

Returns

BoxImage — The image object with updated drawing stroke settings.

Description

Sets the drawing stroke attributes for the specified image. Stroke attributes control how lines and shapes are drawn, including thickness, end cap style, line join style, and dash patterns.

Attribute Collection Keys

The attributeCollection struct supports the following optional keys:

Key	Type	Description	Valid Values
width	float	The stroke width in pixels. Controls the thickness of lines and shape outlines.	Any positive number (e.g., 2.5)
endCaps	string	The end cap style for unclosed subpaths and dash segments.	"butt", "round", "square"
lineJoins	string	The line join style for path segment intersections.	"miter", "round", "bevel"
miterLimit	float	The miter limit for mitered line joins. Controls when a miter join is replaced with a bevel join.	Any positive number (e.g., 10.0)
dashArray	array	An array of floats defining the dash pattern. Alternating values represent lengths of opaque and transparent segments.	Array of floats (e.g., [10, 5, 2, 5])
dashPhase	float	The offset to start the dash pattern. Controls where in the dash pattern to begin.	Any number (e.g., 0.0)

End Cap Styles

• butt - Ends with no added decoration (square end at the endpoint)

• round - Ends with a round decoration (semicircle beyond the endpoint)

• square - Ends with a square projection (square beyond the endpoint)

Line Join Styles

• miter - Joins segments by extending outer edges until they meet

• round - Joins segments by rounding off the corner

• bevel - Joins segments by connecting outer corners with a straight segment

Example

// Set basic stroke width
ImageSetDrawingStroke( myImage, { width: 3.0 } );

// Set width and end cap style
ImageSetDrawingStroke( myImage, { width: 5.0, endCaps: "round" } );

// Create a dashed line
ImageSetDrawingStroke( myImage, {
    width: 2.0,
    dashArray: [10, 5],
    dashPhase: 0
} );

// Full configuration
ImageSetDrawingStroke( myImage, {
    width: 4.0,
    endCaps: "round",
    lineJoins: "miter",
    miterLimit: 10.0,
    dashArray: [15, 5, 5, 5],
    dashPhase: 0
} );

// As a member function (chainable)
myImage.setDrawingStroke({ width: 2 })
       .drawLine(0, 0, 100, 100)
       .setDrawingStroke({ width: 4, dashArray: [5, 5] })
       .drawRect(50, 50, 100, 100, false);

Related BIFs

• ImageSetDrawingColor

• ImageDrawLine

• ImageDrawRect

• ImageDrawOval

• ImageSetAntiAliasing

Notes

• The name argument can be a BoxImage object or the name of an image variable in the current context.

• All attributes in the attributeCollection are optional - only provide the ones you want to change.

• If an attribute is not provided, the corresponding stroke property remains unchanged from its current value.

• The operation modifies the image in place when used as a member function.

• Returns the modified image object for chaining or further processing.

• Default values: width=1.0, endCaps="round", lineJoins="bevel"

• The stroke settings affect all subsequent drawing operations until changed again.