GD::Text(3)
Contents
GD::Text - Text utilities for use with GD
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,
);
This module provides a font-independent way of dealing
with text in GD, for use with the GD::Text::* modules and
GD::Graph.
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.
If you want to refer to builtin GD fonts by their short
name ("gdTinyFont", "gdGiantFont"), you will need to "use"
the GD module as well as one the GD::Text modules, because
it is GD that exports those names into your name space. If
you don't like that, use the longer alternatives
("GD::Font-"Giant>) instead.
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. See also "font_path".
If you are not using an absolute path to the font file,
you can leave of the .ttf file extension, but you have to
append it for absolute paths:
$gd_text->set_font('arial', 12);
# but
$gd_text->set_font('/usr/fonts/arial.ttf', 12);
The first argument can be a reference to an array of
fonts. The first font from the array that can be found
will be used. This allows you to do something like
$gd_text->font_path( '/usr/share/fonts:/usr/fonts');
$gd_text->set_font(
['verdana', 'arial', gdMediumBoldFont], 14);
if you'd prefer verdana to be used, would be satisfied
with arial, but if none of that is available just want to
make sure you can fall back on something that will be
available.
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 fail-
ure, 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.
$gd_text->font_path(path_spec),
GD::Text->font_path(path_spec)
This sets the font path for the class (i.e. not just for
the object). The "set_font" method will search this path
to find the font specified if it is a TrueType font. It
should contain a list of paths. The current directory is
always searched first, unless '.' is present in FONT_PATH.
Examples:
GD::Text->font_path('/usr/ttfonts'); # Unix
GD::Text->font_path('c:/fonts'); # MS-OS
Any font name that is not an absolute path will first be
looked for in the current directory, and then in
/usr/ttfonts (c:\fonts).
GD::Text->font_path('/usr/ttfonts:.:lib/fonts'); # Unix
GD::Text->font_path('c:/fonts;.;f:/fonts'); # MS-OS
Any font name that is not an absolute path will first be
looked for in /usr/ttfonts (c:\fonts), then in the current
directory. and then in lib/fonts (f:\fonts), relative to
the current directory.
GD::Text->font_path(undef);
Font files are only looked for in the current directory.
FONT_PATH is initialised at module load time from the
environment variables FONT_PATH or, if that's not present,
TTF_FONT_PATH, or TT_FONT_PATH.
Returns the value the font path is set to. If called
without arguments "font_path" returns the current font
path.
Note: This currently only works for unices, and (hope-
fully) for Microsoft based OS's. If anyone feels the urge
to have a look at the code, and send me patches for their
OS, I'd be most grateful)
This module has only been tested with anglo-centric 'nor-
mal' fonts and encodings. Fonts that have other charac-
teristics may not work well. If that happens, please let
me know how to make this work better.
The font height gets estimated by building a string with
all printable characters (with an ordinal value between 0
and 255) that pass the POSIX::isprint() test (and not the
isspace() test). If your system doesn't have POSIX, I make
an approximation that may be false. Under Perl 5.8.0 the
[[:print:]] character class is used, since the POSIX is*()
functions don't seem to work correctly.
The whole font path thing works well on Unix, but probably
not very well on other OS's. This is only a problem if you
try to use a font path. If you don't use a font path,
there should never be a problem. I will try to expand this
in the future, but only if there's a demand for it. Sug-
gestions welcome.
copyright 1999 Martien Verbruggen (mgjv@comdyn.com.au)
GD(3), GD::Text::Wrap(3), GD::Text::Align(3)
perl v5.8.0 2003-06-18 Text(3)
[ Index ] [ Back ]