NAME¶
Prima::CurvedText - fit text to path
DESCRIPTION¶
The module registers single function "curved_text_out" in
"Prima::Drawable" namespace. The function plots the line of text
along the path, which given as a set of points. Various options regulate
behavior of the function when glyphs collide with the path boundaries and each
other.
SYNOPSIS¶
use Prima qw(Application CurvedText);
$::application-> begin_paint;
$::application-> curved_text_out( 'Hello, world!',
$::application-> render_spline( [qw(100 100 150 150 200 100)]));
curved_text_out $TEXT, $POLYLINE, %OPTIONS¶
$TEXT is a line of text, no special treatment is given to tab and newline
characters. The text is plotted over $POLYLINE path that should be an array of
coordinate numeric pairs, in the same format as
"Prima::Drawable::polyline" expects.
The text begins to plot by drawing the first glyphs at the first path point,
unless specified otherwise with the "offset" option. The glyph is
plotted with the angle perpendicular to the path segment; therefore the path
may contain floating point numbers if futher plotting angle accuracy is
desired.
When text cannot be fit along a single segment, it is plotted along the next
segment in the path. Depending on the "bevel" boolean option, the
next glyph is either simply drawn on the next segment with the angle
corresponding to the tangent of that segment (value 0), or is drawn with the
normal text concatenation offset, with the angle averaged between tangents of
the two segments it is plotted between (value 1). The default value of
"bevel" option is 1.
The glyph positioning rules differ depending on "collisions" integer
option. If 0 (default), the next glyph position always corresponds with the
glyph width as projected to the path. That means, that glyphs will overlap
when plotted inside segments forming an acute angle. Also, when plotting along
a reflex angle, the glyphs will be visually more distant from each other that
when plotted along the straight line.
Simple collision detection can be turned on with setting "collisions"
to 1 so that no two neighbour glyphs may overlap. Also, the glyphs will be
moved together to the minimal distance, when possible. With this option set
the function will behave slower. If detection of not only neighbouring glyphs
is required, "collisions" value can be set to 2, in which case a
glyph is guaranteedly will never overlap any other glyph. This option may be
needed when, for example, text is plotted inside an acute angle and upper
parts of glyphs plotted along one segment will overlap with lower parts of
glyphs plotted along the other one. Setting "collisions" to 2 will
slow the function even more.
The function internally creates an array of tuples where each contains text,
plotting angle, and horisontal and vertical coordinates for the text to be
plotted. In the array context the function returns this array. In the scalar
context the function returns the success flag that is the result of last call
to "text_out".
Options:
- bevel BOOLEAN=true
- If set, glyphs between two adjoining segments will be plotted with
bevelled angle. Otherwise glyphs will strictly follow the angles of the
segments in the path.
- callback CODE($SELF, $POLYLINE, $CHUNKS)
- If set, the callback is called with $CHUNKS after the calculations were
made but before the text is plotted. $CHUNKS is an array of tuples where
each consists of text, angle, x and y coordinates for each text. The
callback is free to modify the array.
- collisions INTEGER=0
- If 0, collision detection is disabled, glyphs plotted along the path. If
1, no two neighbour glyphs may overlap, and no two neighbour glyph will be
situated further away from each other than it is necessary. If 2, same
functionality as with 1, and also two glyphs (in all text) will
overlap.
- nodraw BOOLEAN=false
- If set, calculate glyph positions but do not draw them.
- offset INTEGER=0
- Sets offset from the beginning of the path where the first glyph is
plotted. If offset is negative, it is calculated from the end of the
path.
- skiptail BOOLEAN=false
- If set, the remainder of the text that is left after the path is
completely traversed, is not shown. Otherwise (default), the tail text is
shown with the angle used to plot the last glyph (if bevelling was
requested) or the angle perpendicular to the last path segment
(otherwise).
AUTHOR¶
Dmitry Karasik, <dmitry@karasik.eu.org>.
SEE ALSO¶
Prima, Prima::Drawable