NAME
GD::Text - Text utilities for use with GD
SYNOPSIS
use GD;
use GD::Text;
my $gd_text = GD::Text->new() or die GD::Text::error();
$gd_text->set_font('funny.ttf', 12) or die $gd_text->error;
$gd_text->set_font(gdTinyFont);
$gd_text->set_font(GD::Font::Tiny);
...
$gd_text->set_text($string);
my ($w, $h) = $gd_text->get('width', 'height');
if ($gd_text->is_ttf)
{
...
}Or alternatively
my $gd_text = GD::Text->new(
text => 'Some text',
font => 'funny.ttf',
ptsize => 14,
);DESCRIPTION
This module provides a font-independent way of dealing with text in GD, for use with the GD::Text::* modules and GD::Graph.
NOTES
As with all Modules for Perl: Please stick to using the interface. If you try to fiddle too much with knowledge of the internals of this module, you could get burned. I may change them at any time.
You can only use TrueType fonts with version of GD > 1.20, and then only if compiled with support for this. If you attempt to do it anyway, you will get errors.
METHODS
GD::Text->new( attrib => value, ... )
Create a new object. See the set() method for attributes.
GD::Text::error() or $gd_text->error();
Return the last error that occured in the class. This may be imperfect.
$gd_text->set_font( font, size )
Set the font to use for this string. The arguments are either a GD builtin font (like gdSmallFont or GD::Font->Small) or the name of a TrueType font file and the size of the font to use.
Returns true on success, false on error.
$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 provides a convenience replacement for the various other set_xxx() methods. Valid attributes are:
- text
-
The text to operate on, see also
set_text(). - font, ptsize
-
The font to use and the point size. The point size is only used for TrueType fonts. Also see
set_font().
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, and:
- width, height
-
The width (height) of the string in pixels
- space
-
The width of a space in pixels
- char_up, char_down
-
The number of pixels that a character can stick out above and below the baseline. Note that this is only useful for TrueType fonts. For builtins char_up is equal to height, and char_down is always 0.
Note that some of these parameters (char_up, char_down and space) are generic font properties, and not necessarily a property of the text that is set.
$gd_text->width('string')
Return the length of a string in pixels, without changing the current value of the text. Returns the width of 'string' rendered in the current font and size. On failure, returns undef.
The use of this method is vaguely deprecated.
$gd_text->is_builtin
Returns true if the current object is based on a builtin GD font.
$gd_text->is_ttf
Returns true if the current object is based on a TrueType font.
$gd_text->can_do_ttf() or GD::Text->can_do_ttf()
Return true if this object can handle TTF fonts.
This depends on whether your version of GD is newer than 1.19 and has TTF support compiled into it.
BUGS
This module has only been tested with anglo-centric 'normal' fonts and encodings. Fonts that have other characteristics may not work well. If that happens, please let me know how to make this work better.
COPYRIGHT
copyright 1999 Martien Verbruggen (mgjv@comdyn.com.au)
SEE ALSO
GD(3), GD::Text::Wrap(3), GD::Text::Align(3)