=head1 NAME
GD::Text::Arc - draw TrueType text along an arc.
=head1 SYNOPSIS
use GD::Text::Arc;
my $image = GD::Image->new(600,500);
my $gray = $image->colorAllocate(75,75,75);
my $boldfont = "Adventure.ttf";
my $text = "here's a line.";
my $ta = GD::Text::Arc->new($image,
colour => $gray,
ptsize => $size,
font => $boldfont,
radius => $radius,
center_x => $centerX,
center_y => $centerY,
text => $text,
side => 'inside'
orientation => 'clockwise'
);
$ta->draw;
$ta->set('color', $red);
$ta->set('ptsize', $huge);
$ta->set('orientation', 'counterclockwise');
$ta->draw;
=head1 DESCRIPTION
This module provides a way to draw TrueType text along a curve (such as
around the bottom or top of a circle). It is to be used with GD::Text
(version > 1.20) and GD graphics objects.
=head1 METHODS
=head2 GD::Text->new($gd_object, attrib => value, ... )
Create a new object. The first argument has to be a valid GD::Image
object. See the C<set()> method for attributes.
=head2 $gd_text->set_font( font, size )
Set the font to use for the string, using absolute or relative
TrueType font names. See L<"GD::Text"> and L<"GD::Text::font_path">
for details.
=head2 $gd_text->set_text('some text')
Set the text to operate on.
Returns true on success and false on error.
=head2 $gd_text->set( attrib => value, ... )
The set method is the preferred way to set attributes.
Valid attributes are:
=over 4
=item text
The text to operate on, see also C<set_text()>.
=item font, ptsize
The font to use and the point size. Also see C<set_font()>.
=item colour, color
Synonyms. The colour to use to draw the string. This should be the index
of the colour in the GD::Image object's palette. The default value is
the last colour in the GD object's palette at the time of the creation
of C<$gd_text>.
=item center_x, center_y
The center point for the circle. Defaults to 1/2 the width and height
of the containing GD object.
=item radius
The radius of the circle, which is either drawn outside or inside the
text (depending on C<side> attribute; see below). The default
radius is the lesser of center_x or center_y.
=item orientation
Direction of the text. Valid values: clockwise, counterclockwise.
Default is counterclockwise (that is, written along the bottom of the
circle, such as from 8-oclock to 5-oclock on a clock face.)
=item side
Whether the text is drawn inside the radius of the circle or outside.
Valid values: inside, outside. Default is outside.
=item align
Not implemented yet; but will allow text to be left- or right- aligned
around a point on the circle. At present, text is center-aligned..
=item angle
Not implemented yet; but will set the point on the circle around which
text is centered (or started or ended, depending on alignment). At
present, angle is set to 0 (top of the circle) for clockwise
orientation, and PI (bottom of the circle) for counterclockwise
orientation.
=item compress_factor, points_to_pixels_factor
These parameters were found by experimentation and seem to apply to
any fonts and point-sizes I've tried, but might need adjusting under
some situations.
compress_factor adjusts spacing between characters. It is .9 by
default; a larger value reduces the space between characters.
points_to_pixels_factor adjusts the radius (by a fraction of the
point-size) to compensate for the height of letters.
It is .8 by default; a larger value increases the radius.
=back
Returns true on success, false on any error, even if it was partially
successful. When an error is returned, no guarantees are given about
the correctness of the attributes.
=head2 $gd_text->get( attrib, ... )
Get the value of an attribute.
Return a list of the attribute values in list context, and the value of
the first attribute in scalar context.
The attributes that can be retrieved are all the ones that can be set,
plus those described in L<"GD::Text">.:
Note that unlike with GD::Text::Align, you can get() both 'color' and
'colour'. Vive la difference!
=head2 $gd_text->get_widths()
In array context, returns a list of character-widths for the text to
be drawn. In scalar context, return the total width of the string
measured in pixels. Because the way the characters are drawn (to
acount for kerning between adjacent characters), this is more accurate
than $gd_text->width. This is mostly an internal method, but might be
useful to make sure your text is shorter than, say, PI * radius
characters.
=head2 $gd_text->draw()
Draw the string according to coordinates, radius, orientation, and font.
Returns true on success, false on any error.
=head1 NOTES
=head2 GD::Text::Arc::PI
Owing to how 'use constant' works, for free, you get a definition of Pi
that is as good as your floating-point math. You can also access it
as method C<$gd_text-E<gt>PI>.
=head1 BUGS
Probably.
I haven't implemented align() or angle() methods yet;
for now, align = center and angle = 0. I'm not sure this module will work
perfectly with all fonts. I've tried it with a few dozen, which look more
or less the way I wanted them to.
Suggestions gratefully welcomed.
=head1 COPYRIGHT
Copyright (C) 2004
Daniel Allen E<lt>da@coder.comE<gt>. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>
=head1 SEE ALSO
GD(3), GD::Text(3), GD::Text::Wrap(3), GD::Text::Align(3)
=cut
|