Prima::Drawable::CurvedText(3pm)

1Prima::Drawable::CurvedUTseexrt(C3o)ntributed Perl DocumPernitmaat:i:oDnrawable::CurvedText(3)
2
3
4

NAME

6       Prima::Drawable::CurvedText - fit text to path
7

DESCRIPTION

9       The module registers single function "curved_text_out" in
10       "Prima::Drawable" namespace. The function plots the line of text along
11       the path, which given as a set of points. Various options regulate
12       behavior of the function when glyphs collide with the path boundaries
13       and each other.
14

SYNOPSIS

16         use Prima qw(Application Drawable::CurvedText);
17         my $spline = [qw(100 100 150 150 200 100)];
18         $::application-> begin_paint;
19         $::application-> spline($spline);
20         $::application-> curved_text_out( 'Hello, world!', $::application-> render_spline( $spline ));
21
22   curved_text_out $TEXT, $POLYLINE, %OPTIONS
23       $TEXT is a line of text, no special treatment is given to tab and
24       newline characters.  The text is plotted over $POLYLINE path that
25       should be an array of coordinate numeric pairs, in the same format as
26       "Prima::Drawable::polyline" expects.
27
28       The text begins to plot by drawing the first glyphs at the first path
29       point, unless specified otherwise with the "offset" option. The glyph
30       is plotted with the angle perpendicular to the path segment; therefore
31       the path may contain floating point numbers if futher plotting angle
32       accuracy is desired.
33
34       When text cannot be fit along a single segment, it is plotted along the
35       next segment in the path. Depending on the "bevel" boolean option, the
36       next glyph is either simply drawn on the next segment with the angle
37       corresponding to the tangent of that segment (value 0), or is drawn
38       with the normal text concatenation offset, with the angle averaged
39       between tangents of the two segments it is plotted between (value 1).
40       The default value of "bevel" option is 1.
41
42       The glyph positioning rules differ depending on "collisions" integer
43       option. If 0 (default), the next glyph position always corresponds with
44       the glyph width as projected to the path. That means, that glyphs will
45       overlap when plotted inside segments forming an acute angle. Also, when
46       plotting along a reflex angle, the glyphs will be visually more distant
47       from each other that when plotted along the straight line.
48
49       Simple collision detection can be turned on with setting "collisions"
50       to 1 so that no two neighbour glyphs may overlap. Also, the glyphs will
51       be moved together to the minimal distance, when possible. With this
52       option set the function will behave slower. If detection of not only
53       neighbouring glyphs is required, "collisions" value can be set to 2, in
54       which case a glyph is guaranteedly will never overlap any other glyph.
55       This option may be needed when, for example, text is plotted inside an
56       acute angle and upper parts of glyphs plotted along one segment will
57       overlap with lower parts of glyphs plotted along the other one.
58       Setting "collisions" to 2 will slow the function even more.
59
60       The function internally creates an array of tuples where each contains
61       text, plotting angle, and horisontal and vertical coordinates for the
62       text to be plotted. In the array context the function returns this
63       array. In the scalar context the function returns the success flag that
64       is the result of last call to "text_out".
65
66       Options:
67
68       bevel BOOLEAN=true
69           If set, glyphs between two adjoining segments will be plotted with
70           bevelled angle.  Otherwise glyphs will strictly follow the angles
71           of the segments in the path.
72
73       callback CODE($SELF, $POLYLINE, $CHUNKS)
74           If set, the callback is called with $CHUNKS after the calculations
75           were made but before the text is plotted. $CHUNKS is an array of
76           tuples where each consists of text, angle, x and y coordinates for
77           each text. The callback is free to modify the array.
78
79       collisions INTEGER=0
80           If 0, collision detection is disabled, glyphs plotted along the
81           path. If 1, no two neighbour glyphs may overlap, and no two
82           neighbour glyph will be situated further away from each other than
83           it is necessary. If 2, same functionality as with 1, and also two
84           glyphs (in all text) will overlap.
85
86       nodraw BOOLEAN=false
87           If set, calculate glyph positions but do not draw them.
88
89       offset INTEGER=0
90           Sets offset from the beginning of the path where the first glyph is
91           plotted.  If offset is negative, it is calculated from the end of
92           the path.
93
94       skiptail BOOLEAN=false
95           If set, the remainder of the text that is left after the path is
96           completely traversed, is not shown. Otherwise (default), the tail
97           text is shown with the angle used to plot the last glyph (if
98           bevelling was requested) or the angle perpendicular to the last
99           path segment (otherwise).
100

AUTHOR

102       Dmitry Karasik, <dmitry@karasik.eu.org>.
103

NAME

DESCRIPTION

SYNOPSIS

AUTHOR

SEE ALSO