{
    "mode": "perldoc",
    "parameter": "GD::Text",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/GD%3A%3AText/json",
    "generated": "2026-06-12T11:46:39Z",
    "synopsis": "use GD;\nuse GD::Text;\nmy $gdtext = GD::Text->new() or die GD::Text::error();\n$gdtext->setfont('funny.ttf', 12) or die $gdtext->error;\n$gdtext->setfont(gdTinyFont);\n$gdtext->setfont(GD::Font::Tiny);\n...\n$gdtext->settext($string);\nmy ($w, $h) = $gdtext->get('width', 'height');\nif ($gdtext->isttf)\n{\n...\n}\nOr alternatively\nmy $gdtext = GD::Text->new(\ntext => 'Some text',\nfont => 'funny.ttf',\nptsize => 14,\n);",
    "sections": {
        "NAME": {
            "content": "GD::Text - Text utilities for use with GD\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use GD;\nuse GD::Text;\n\nmy $gdtext = GD::Text->new() or die GD::Text::error();\n$gdtext->setfont('funny.ttf', 12) or die $gdtext->error;\n$gdtext->setfont(gdTinyFont);\n$gdtext->setfont(GD::Font::Tiny);\n...\n$gdtext->settext($string);\nmy ($w, $h) = $gdtext->get('width', 'height');\n\nif ($gdtext->isttf)\n{\n...\n}\n\nOr alternatively\n\nmy $gdtext = GD::Text->new(\ntext => 'Some text',\nfont => 'funny.ttf',\nptsize => 14,\n);\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This module provides a font-independent way of dealing with text in GD, for use with the\nGD::Text::* modules and GD::Graph.\n",
            "subsections": []
        },
        "NOTES": {
            "content": "As with all Modules for Perl: Please stick to using the interface. If you try to fiddle too much\nwith knowledge of the internals of this module, you could get burned. I may change them at any\ntime.\n\nYou can only use TrueType fonts with version of GD > 1.20, and then only if compiled with\nsupport for this. If you attempt to do it anyway, you will get errors.\n\nIf you want to refer to builtin GD fonts by their short name (\"gdTinyFont\", \"gdGiantFont\"), you\nwill need to \"use\" the GD module as well as one the GD::Text modules, because it is GD that\nexports those names into your name space. If you don't like that, use the longer alternatives\n(\"GD::Font-\"Giant>) instead.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "GD::Text->new( attrib => value, ... )\nCreate a new object. See the \"set()\" method for attributes.\n\nGD::Text::error() or $gdtext->error();\nReturn the last error that occurred in the class. This may be imperfect.\n\n$gdtext->setfont( font, size )\nSet the font to use for this string. The arguments are either a GD builtin font (like\ngdSmallFont or GD::Font->Small) or the name of a TrueType font file and the size of the font to\nuse. See also \"fontpath\".\n\nIf you are not using an absolute path to the font file, you can leave of the .ttf file\nextension, but you have to append it for absolute paths:\n\n$gdtext->setfont('arial', 12);\n# but\n$gdtext->setfont('/usr/fonts/arial.ttf', 12);\n\nThe first argument can be a reference to an array of fonts. The first font from the array that\ncan be found will be used. This allows you to do something like\n\n$gdtext->fontpath( '/usr/share/fonts:/usr/fonts');\n$gdtext->setfont(\n['verdana', 'arial', gdMediumBoldFont], 14);\n\nif you'd prefer verdana to be used, would be satisfied with arial, but if none of that is\navailable just want to make sure you can fall back on something that will be available.\n\nReturns true on success, false on error.\n\nelsif ($OS =~ /^MacOS/i)\n{\n# Check for absolute path\n$font =~ /:/ and $font !~ /^:/ and return $font;\n$psep = ':';\n$dsep = ',';\n}\nelsif ($OS =~ /^AmigaOS/i)\n{\n# What's an absolute path here?\n$psep = '/';\n$dsep = ':'; # XXX ?\n}\nelsif ($OS =~ /^VMS/i)\n{\n# What's an absolute path here?\n$psep = '/';\n$dsep = ':';\n}\n\n$gdtext->settext('some text')\nSet the text to operate on. Returns true on success and false on error.\n\n$gdtext->set( attrib => value, ... )\nThe set method provides a convenience replacement for the various other \"setxxx()\" methods.\nValid attributes are:\n\ntext\nThe text to operate on, see also \"settext()\".\n\nfont, ptsize\nThe font to use and the point size. The point size is only used for TrueType fonts. Also see\n\"setfont()\".\n\nReturns true on success, false on any error, even if it was partially successful. When an error\nis returned, no guarantees are given about the correctness of the attributes.\n\n$gdtext->get( attrib, ... )\nGet the value of an attribute. Return a list of the attribute values in list context, and the\nvalue of the first attribute in scalar context.\n\nThe attributes that can be retrieved are all the ones that can be set, and:\n\nwidth, height\nThe width (height) of the string in pixels\n\nspace\nThe width of a space in pixels\n\ncharup, chardown\nThe number of pixels that a character can stick out above and below the baseline. Note that\nthis is only useful for TrueType fonts. For builtins charup is equal to height, and\nchardown is always 0.\n\nNote that some of these parameters (charup, chardown and space) are generic font properties,\nand not necessarily a property of the text that is set.\n\n$gdtext->width('string')\nReturn the length of a string in pixels, without changing the current value of the text. Returns\nthe width of 'string' rendered in the current font and size. On failure, returns undef.\n\nThe use of this method is vaguely deprecated.\n\n$gdtext->isbuiltin\nReturns true if the current object is based on a builtin GD font.\n\n$gdtext->isttf\nReturns true if the current object is based on a TrueType font.\n\n$gdtext->candottf() or GD::Text->candottf()\nReturn true if this object can handle TTF fonts.\n\nThis depends on whether your version of GD is newer than 1.19 and has TTF support compiled into\nit.\n\n$gdtext->fontpath(pathspec), GD::Text->fontpath(pathspec)\nThis sets the font path for the *class* (i.e. not just for the object). The \"setfont\" method\nwill search this path to find the font specified if it is a TrueType font. It should contain a\nlist of paths. The current directory is always searched first, unless '.' is present in\nFONTPATH. Examples:\n\nGD::Text->fontpath('/usr/ttfonts'); # Unix\nGD::Text->fontpath('c:/fonts');     # MS-OS\n\nAny font name that is not an absolute path will first be looked for in the current directory,\nand then in /usr/ttfonts (c:\\fonts).\n\nGD::Text->fontpath('/usr/ttfonts:.:lib/fonts'); # Unix\nGD::Text->fontpath('c:/fonts;.;f:/fonts');      # MS-OS\n\nAny font name that is not an absolute path will first be looked for in /usr/ttfonts (c:\\fonts),\nthen in the current directory. and then in lib/fonts (f:\\fonts), relative to the current\ndirectory.\n\nGD::Text->fontpath(undef);\n\nFont files are only looked for in the current directory.\n\nFONTPATH is initialised at module load time from the environment variables FONTPATH or, if\nthat's not present, TTFFONTPATH, or TTFONTPATH.\n\nReturns the value the font path is set to. If called without arguments \"fontpath\" returns the\ncurrent font path.\n\nNote: This currently only works for unices, and (hopefully) for Microsoft based OS's. If anyone\nfeels the urge to have a look at the code, and send me patches for their OS, I'd be most\ngrateful)\n",
            "subsections": []
        },
        "BUGS": {
            "content": "This module has only been tested with anglo-centric 'normal' fonts and encodings. Fonts that\nhave other characteristics may not work well. If that happens, please let me know how to make\nthis work better.\n\nThe font height gets estimated by building a string with all printable characters (with an\nordinal value between 0 and 255) that pass the POSIX::isprint() test (and not the isspace()\ntest). If your system doesn't have POSIX, I make an approximation that may be false. Under Perl\n5.8.0 the [[:print:]] character class is used, since the POSIX is*() functions don't seem to\nwork correctly.\n\nThe whole font path thing works well on Unix, but probably not very well on other OS's. This is\nonly a problem if you try to use a font path. If you don't use a font path, there should never\nbe a problem. I will try to expand this in the future, but only if there's a demand for it.\nSuggestions welcome.\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "copyright 1999 Martien Verbruggen (mgjv@comdyn.com.au)\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "GD(3), GD::Text::Wrap(3), GD::Text::Align(3)\n",
            "subsections": []
        }
    },
    "summary": "GD::Text - Text utilities for use with GD",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "GD",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/GD/3/json"
        },
        {
            "name": "Wrap",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Wrap/3/json"
        },
        {
            "name": "Align",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Align/3/json"
        }
    ]
}