GD::Text - phpMan

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

    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.

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

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.

    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
    copyright 1999 Martien Verbruggen (mgjv AT comdyn.au)

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