ImageSetDrawingStroke

Description

Sets the drawing stroke for points and lines in subsequent ColdFusion images.

Returns

Nothing.

Function syntax

ImageSetDrawingStroke(name [, attributeCollection])

History

ColdFusion 8: Added this function.

Parameters

Parameter

Description

name

Required. The ColdFusion image on which this operation is performed.

attributeCollection

Optional. The structure used to specify the line attributes. See the Usage section.

Usage

Use the ImageSetDrawingStroke function to control the line attributes of all subsequent drawing objects in a ColdFusion image. For example, you can use this function to set the drawing stroke to a dash pattern once, and then create a rectangle, two ovals, and five lines with that pattern.

If a blank or no attribute structure is passed, the drawing stroke is reset to the default values.

attributeCollection

Element

Description

width

Pen width, which is measured perpendicularly to the pen trajectory.

endcaps

Decoration applied to the ends of unclosed subpaths and dash segments. Subpaths that start and end on the same point are considered unclosed if they do not have a close segment:

  • butt

  • round

  • square

lineJoins

Type of line joins:

  • bevel

  • miter

  • join

miterLimit

The limit to trim a line join that has a mitered join decoration. (Use only when lineJoins = "miter".) 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 value is 10.0, which trims all angles less than 11 degrees. Trimming miters converts the decoration of the line join to bevel.

dashArray

An array of numbers that indicates the dash pattern. For example. if dashArray is (8,4), the dash pattern is 8 pixels solid, 4 pixels blank, 8 pixels solid, 4 pixels blank, and so on.

dash_phases

An offset into the dash pattern. For example, a dash_phase of 2, and a dashArray of (8,4) produces the dash pattern of 6 pixels solid, 4 pixels blank, 8 pixels solid, 4 pixels blank, and so on.

Example

Example 1

<!--- This example shows how to create an attribute collection for the ImageSetDrawingStroke function and draws a line with those attributes. 
    ---> 
<!--- Use the ImageNew function to create a ColdFusion image. ---> 
<cfset myImage=ImageNew("",200,200)> 
<!--- Create an attribute collection to pass to the ImageSetDrawingStroke function. Create a stroke that is 10-pixels wide, has round endcaps, and has a dash pattern of (8,4). ---> 
<cfset attr = StructNew()> 
<cfset attr.width = 2> 
<cfset attr.endcaps = "round"> 
<cfset dashPattern = ArrayNew(1)> 
<cfset dashPattern[1] = 8> 
<cfset dashPattern[2] = 4> 
<cfset attr.dashArray = dashPattern> 
<!--- Apply the attribute collection to the ImageSetDrawingStroke function for the image. ---> 
<cfset ImageSetDrawingStroke(myImage,attr)> 
<!--- Draw a line on the ColdFusion image with the drawing stroke attributes. ---> 
<cfset ImageDrawLine(myImage,20,20,40,150)> 
<!--- Display the image in a browser. ---> 
<cfimage source="#myImage#" action="writeToBrowser">

Example 2

<!--- Use the ImageNew function to create a ColdFusion image. ---> 
<cfset myImage=ImageNew("",500,500)> 
<!-- Set the drawing color of the image to cyan. ---> 
<cfset ImageSetDrawingColor(myImage,"cyan")> 
<!--- Draw a line from (30,40) to (200,190). ---> 
<cfset ImageDrawLine(myImage,30,30,200,200)> 
<!--- Create the attribute collection for the drawing stroke. ---> 
<cfset attr = StructNew()> 
<cfset attr.width = 1> 
<cfset attr.endcaps = "round"> 
<cfset dashPattern = ArrayNew(1)> 
<cfset dashPattern[1] = 3> 
<cfset dashPattern[2] = 4> 
<cfset dashPattern[3] = 8> 
<cfset attr.dashArray = dashPattern> 
<!--- Pass the attribute collection as an argument to the set drawing stroke 
function. ---> 
<cfset ImageSetDrawingStroke(myImage,attr)> 
<!-- Set the drawing color of the image to yellow. ---> 
<cfset ImageSetDrawingColor(myImage,"yellow")> 
<!--- Draw a rectangle with the drawing stroke specified. ---> 
<cfset ImageDrawRect(myImage,200,50,210,200)> 
<!-- Reset the drawing stroke. --> 
<cfset ImageSetDrawingStroke(myImage)> 
<!--- Draw a green quadratic curve. ---> 
<cfset ImageSetDrawingColor(myImage,"green")> 
<cfset ImageDrawQuadraticCurve(myImage,120,320,5,15,380,280)> 
<!--- Display the image in a browser. ---> 
<cfimage source="#myImage#" action="writeToBrowser">