Prima::Drawable::CurvedText - fit text to path
The module registers a single function curved_text_out in the Prima::Drawable namespace. The function plots a line of text along the path defined as a set of points. Various options regulate the behavior of the function when individual glyphs collide with either the path boundaries or each other.
curved_text_out
Prima::Drawable
use Prima qw(Application Drawable::CurvedText); my $spline = [qw(100 100 150 150 200 100)]; $::application-> begin_paint; $::application-> spline($spline); $::application-> curved_text_out( 'Hello, world!', $::application-> render_spline( $spline ));
$TEXT is a line of text, no special treatment is given to tab and newline characters. The text is plotted over $POLYLINE path that is an array of coordinate numeric pairs, in the same format as the Prima::Drawable::polyline method expects.
$TEXT
$POLYLINE
Prima::Drawable::polyline
The plotting begins by drawing the first glyph at the first point in the path unless specified otherwise with the offset option. The glyph is plotted with the angle perpendicular to the first path segment; therefore the path may contain floating point numbers if better angle accuracy is desired.
offset
When the text cannot be fit along a segment it is plotted along the next segment in the path. Depending on the bevel boolean option, the next glyph is either 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 the bevel option is 1.
bevel
The glyph positioning rules differ depending on the collisions integer option. If the option is set to 0 (default), the next glyph position always corresponds to the glyph width as projected to the path. This 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 than when plotted along a straight line.
collisions
Simple collision detection can be turned on by setting the collisions option to 1 so that no two adjacent glyphs may overlap. The glyphs will be placed together with a minimal distance between them, when possible. With this option set, the function will behave slower. This detection works only for the adjacent glyphs; if the detection of all glyphs in the text is needed, the collisions value 2 turns that on. This option may be needed when, for example, the text is plotted inside an acute angle, and the upper parts of glyphs plotted along one segment will overlap the 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 the text string, plotting angle, and the X,Y coordinates for the text to be plotted. If called in the array context, the function returns this array. In the scalar context, the function returns the success flag that is the result of the last call to the text_out function.
text_out
Options:
If set, the glyphs between two adjoining segments will be plotted with a beveled angle. Otherwise, the glyphs will strictly follow the tangents of the segments in the path.
If set, the callback is called with $CHUNKS after the calculations are made but before the text is plotted. $CHUNKS is an array of tuples where each consists of text, angle, and X,Y coordinates for each text. The callback is free to modify the array.
$CHUNKS
If 0, collision detection is disabled, and text glyphs are plotted strictly along the path. If 1, no two adjacent glyphs may overlap, and no two adjacent glyphs will be situated further away from each other than is necessary. If 2, the same functionality as with 1, and also no two glyphs in the whole text will overlap.
If set, calculate glyph positions but do not draw them.
Sets a pixel offset from the beginning of the path where the first glyph is plotted. If the offset is negative, it is calculated from the end of the path.
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).
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, Prima::Drawable
To install Prima, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prima
CPAN shell
perl -MCPAN -e shell install Prima
For more information on module installation, please visit the detailed CPAN module installation guide.