.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Prima::CurvedText 3"
.TH Prima::CurvedText 3 "2009-02-24" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Prima::CurvedText \- fit text to path
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The module registers single function \f(CW\*(C`curved_text_out\*(C'\fR in \f(CW\*(C`Prima::Drawable\*(C'\fR
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.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  use Prima qw(Application CurvedText);
\&  $::application\-> begin_paint;
\&  $::application\-> curved_text_out( \*(AqHello, world!\*(Aq,
\&    $::application\-> render_spline( [qw(100 100 150 150 200 100)]));
.Ve
.ie n .SS "curved_text_out $TEXT, $POLYLINE, %OPTIONS"
.el .SS "curved_text_out \f(CW$TEXT\fP, \f(CW$POLYLINE\fP, \f(CW%OPTIONS\fP"
.IX Subsection "curved_text_out $TEXT, $POLYLINE, %OPTIONS"
\&\f(CW$TEXT\fR is a line of text, no special treatment is given to tab and newline characters.
The text is plotted over \f(CW$POLYLINE\fR path that should be an array of coordinate 
numeric pairs, in the same format as \f(CW\*(C`Prima::Drawable::polyline\*(C'\fR expects.
.PP
The text begins to plot by drawing the first glyphs at the first path point, unless
specified otherwise with the \f(CW\*(C`offset\*(C'\fR 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.
.PP
When text cannot be fit along a single segment, it is plotted along the next segment in the
path. Depending on the \f(CW\*(C`bevel\*(C'\fR 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
\&\f(CW\*(C`bevel\*(C'\fR option is 1.
.PP
The glyph positioning rules differ depending on \f(CW\*(C`collisions\*(C'\fR 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.
.PP
Simple collision detection can be turned on with setting \f(CW\*(C`collisions\*(C'\fR 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, \f(CW\*(C`collisions\*(C'\fR 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 \f(CW\*(C`collisions\*(C'\fR to 2 will slow the function
even more.
.PP
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 \f(CW\*(C`text_out\*(C'\fR.
.PP
Options:
.IP "bevel BOOLEAN=true" 4
.IX Item "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.
.ie n .IP "callback \s-1CODE\s0($SELF, $POLYLINE, $CHUNKS)" 4
.el .IP "callback \s-1CODE\s0($SELF, \f(CW$POLYLINE\fR, \f(CW$CHUNKS\fR)" 4
.IX Item "callback CODE($SELF, $POLYLINE, $CHUNKS)"
If set, the callback is called with \f(CW$CHUNKS\fR after the calculations were made
but before the text is plotted. \f(CW$CHUNKS\fR 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.
.IP "collisions INTEGER=0" 4
.IX Item "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.
.IP "nodraw BOOLEAN=false" 4
.IX Item "nodraw BOOLEAN=false"
If set, calculate glyph positions but do not draw them.
.IP "offset INTEGER=0" 4
.IX Item "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.
.IP "skiptail BOOLEAN=false" 4
.IX Item "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).
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Prima, Prima::Drawable