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

    elsif ($OS =~ /^MacOS/i)   
    { 
        # Check for absolute path
        $font =~ /:/ and $font !~ /^:/ and return $font;
        $psep = ':';
        $dsep = ',';
    }
    elsif ($OS =~ /^AmigaOS/i) 
    { 
        # What's an absolute path here? 
        $psep = '/';
        $dsep = ':'; # XXX ?
    }
    elsif ($OS =~ /^VMS/i)
    { 
        # What's an absolute path here? 
        $psep = '/';
        $dsep = ':';
    }

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

$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 (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)