Xojo Conferences

DynaPDF Manual - Page 696

Previous Page 695   Index   Next Page 697

Function Reference
Page 696 of 770
LBOOL pdfSetLineDashPattern(
const PPDF* IPDF, // Instance pointer
const char* Dash, // Dash array defined as string
SI32 Phase)
// The pattern's phase
The line dash pattern controls the pattern of dashes and gaps used to stroke paths. It is specified by a
dash array and a dash phase. The dash array’s elements are numbers that specify the lengths of
alternating dashes and gaps; the dash phase specifies the distance into the dash pattern at which to
start the dash. The elements of both the dash array and the dash phase are expressed in user space
units. Before beginning to stroke a path, the dash array is cycled through, adding up the lengths of
dashes and gaps. When the accumulated length equals the value specified by the dash phase,
stroking of the path begins, using the dash array cyclically from that point onward. The table shows
examples of line dash patterns. As can be seen from the table, an empty dash array and zero phase
can be used to restore the dash pattern to a solid line (you can also use ResetLineDashPattern()).
Dash & Phase Appearance
(NULL, 0)
No dash; solid, unbroken lines
("3", 0)
3 units on, 3 units off…
("2", 1)
1 on, 2 off, 2 on, 2 off, …
("2 1", 0)
2 on, 1 off, 2 on, 1 off, …
("3 5", 6)
2 off, 3 on, 5 off, 3 on, 5 off, ...
("2 3", 11)
1 on, 3 off, 2 on, 3 off, 2 on, ...
Dashed lines wrap around curves and corners just as solid stroked lines do. The ends of each dash
are treated with the current line cap style, and corners within dashes are treated with the current line
join style. A stroking operation takes no measures to coordinate the dash pattern with features of the
path; it simply dispenses dashes and gaps along the path in the pattern defined by the dash array.
When a path consisting of several sub paths is stroked, each sub path is treated independently - that
is, the dash pattern is restarted and the dash phase is reapplied to it at the beginning of each sub
How to create a dotted line?
As described above, a line dash pattern is drawn by applying the current line cap style and join style.
A round cap is painted as semicircular arc with a diameter equal to the line width. If we set the
length of the first on-state to 0 then we get a circle, or dot. The second number of the dash array
specifies the length of the off-state measured from the centers of our circles.
It is quite easy to draw the line now:
pdfSetLineWidth(pdf, 30);

Previous topic: SetLineCapStyle

Next topic: SetLineDashPatternEx, SetLineJoinStyle