NAME

GD::Text::Arc - draw TrueType text along an arc.

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;

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.

METHODS

GD::Text->new($gd_object, attrib => value, ... )

Create a new object. The first argument has to be a valid GD::Image object. See the set() method for attributes.

$gd_text->set_font( font, size )

Set the font to use for the string, using absolute or relative TrueType font names. See "GD::Text" and "GD::Text::font_path" for details.

$gd_text->set_text('some text')

Set the text to operate on. Returns true on success and false on error.

$gd_text->set( attrib => value, ... )

The set method is the preferred way to set attributes. Valid attributes are:

text

The text to operate on, see also set_text().

font, ptsize

The font to use and the point size. Also see set_font().

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 $gd_text.

center_x, center_y

The center point for the circle. Defaults to 1/2 the width and height of the containing GD object.

radius

The radius of the circle, which is either drawn outside or inside the text (depending on side attribute; see below). The default radius is the lesser of center_x or center_y.

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.)

side

Whether the text is drawn inside the radius of the circle or outside. Valid values: inside, outside. Default is outside.

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..

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.

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.

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.

$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 "GD::Text".:

Note that unlike with GD::Text::Align, you can get() both 'color' and 'colour'. Vive la difference!

$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.

$gd_text->draw()

Draw the string according to coordinates, radius, orientation, and font. Returns true on success, false on any error.

NOTES

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 $gd_text->PI.

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.

COPYRIGHT

Copyright (C) 2004 Daniel Allen <da@coder.com>. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

SEE ALSO

GD(3), GD::Text(3), GD::Text::Wrap(3), GD::Text::Align(3)

cpanm GD::Text::Arc

perl -MCPAN -e shell
install GD::Text::Arc