DynaPDF Manual - Page 756

Previous Page 755   Index   Next Page 757

Function Reference
Page 756 of 839
LBOOL pdfSetLineDashPattern2(
const PPDF* IPDF,
// Instance pointer
const float* Dash, // Dash array defined
UI32 NumValues,
// Number of values in the dash array
float 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 path.
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:

Previous topic: SetLineCapStyle, SetLineDashPattern (obsolete)

Next topic: SetLineDashPatternEx (obsolete), SetLineJoinStyle