Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Text(3)		      User Contributed Perl Documentation	       Text(3)

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

       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

	 $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');
	   ['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

   $gd_text->set( attrib => value, ... )
       The set method provides a convenience replacement for the various other
       "set_xxx()" methods. Valid attributes are:

	   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

       The attributes that can be retrieved are	all the	ones that can be set,

       width, height
	   The width (height) of the string in pixels

	   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.

       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.

       Returns true if the current object is based on a	builtin	GD font.

       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.


       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

       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 (hopefully) 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 '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.

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

       copyright 1999 Martien Verbruggen (

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

       Hey! The	above document had some	coding errors, which are explained

       Around line 197:
	   =pod	directives shouldn't be	over one line long!  Ignoring all 20
	   lines of content

perl v5.32.1			  2003-06-19			       Text(3)


Want to link to this manual page? Use this URL:

home | help