GD::Text(3pm)

1Text(3)               User Contributed Perl Documentation              Text(3)
2
3
4

NAME

6       GD::Text - Text utilities for use with GD
7

SYNOPSIS

9         use GD;
10         use GD::Text;
11
12         my $gd_text = GD::Text->new() or die GD::Text::error();
13         $gd_text->set_font('funny.ttf', 12) or die $gd_text->error;
14         $gd_text->set_font(gdTinyFont);
15         $gd_text->set_font(GD::Font::Tiny);
16         ...
17         $gd_text->set_text($string);
18         my ($w, $h) = $gd_text->get('width', 'height');
19
20         if ($gd_text->is_ttf)
21         {
22             ...
23         }
24
25       Or alternatively
26
27         my $gd_text = GD::Text->new(
28               text => 'Some text',
29               font => 'funny.ttf',
30               ptsize => 14,
31           );
32

DESCRIPTION

34       This module provides a font-independent way of dealing with text in GD,
35       for use with the GD::Text::* modules and GD::Graph.
36

NOTES

38       As with all Modules for Perl: Please stick to using the interface. If
39       you try to fiddle too much with knowledge of the internals of this mod‐
40       ule, you could get burned. I may change them at any time.
41
42       You can only use TrueType fonts with version of GD > 1.20, and then
43       only if compiled with support for this. If you attempt to do it anyway,
44       you will get errors.
45
46       If you want to refer to builtin GD fonts by their short name ("gdTiny‐
47       Font", "gdGiantFont"), you will need to "use" the GD module as well as
48       one the GD::Text modules, because it is GD that exports those names
49       into your name space. If you don't like that, use the longer alterna‐
50       tives ("GD::Font-"Giant>) instead.
51

METHODS

53       GD::Text->new( attrib => value, ... )
54
55       Create a new object. See the "set()" method for attributes.
56
57       GD::Text::error() or $gd_text->error();
58
59       Return the last error that occured in the class. This may be imperfect.
60
61       $gd_text->set_font( font, size )
62
63       Set the font to use for this string. The arguments are either a GD
64       builtin font (like gdSmallFont or GD::Font->Small) or the name of a
65       TrueType font file and the size of the font to use. See also
66       "font_path".
67
68       If you are not using an absolute path to the font file, you can leave
69       of the .ttf file extension, but you have to append it for absolute
70       paths:
71
72         $gd_text->set_font('arial', 12);
73         # but
74         $gd_text->set_font('/usr/fonts/arial.ttf', 12);
75
76       The first argument can be a reference to an array of fonts. The first
77       font from the array that can be found will be used. This allows you to
78       do something like
79
80         $gd_text->font_path( '/usr/share/fonts:/usr/fonts');
81         $gd_text->set_font(
82           ['verdana', 'arial', gdMediumBoldFont], 14);
83
84       if you'd prefer verdana to be used, would be satisfied with arial, but
85       if none of that is available just want to make sure you can fall back
86       on something that will be available.
87
88       Returns true on success, false on error.
89
90       $gd_text->set_text('some text')
91
92       Set the text to operate on.  Returns true on success and false on
93       error.
94
95       $gd_text->set( attrib => value, ... )
96
97       The set method provides a convenience replacement for the various other
98       "set_xxx()" methods. Valid attributes are:
99
100       text
101           The text to operate on, see also "set_text()".
102
103       font, ptsize
104           The font to use and the point size. The point size is only used for
105           TrueType fonts. Also see "set_font()".
106
107       Returns true on success, false on any error, even if it was partially
108       successful. When an error is returned, no guarantees are given about
109       the correctness of the attributes.
110
111       $gd_text->get( attrib, ... )
112
113       Get the value of an attribute.  Return a list of the attribute values
114       in list context, and the value of the first attribute in scalar con‐
115       text.
116
117       The attributes that can be retrieved are all the ones that can be set,
118       and:
119
120       width, height
121           The width (height) of the string in pixels
122
123       space
124           The width of a space in pixels
125
126       char_up, char_down
127           The number of pixels that a character can stick out above and below
128           the baseline. Note that this is only useful for TrueType fonts. For
129           builtins char_up is equal to height, and char_down is always 0.
130
131       Note that some of these parameters (char_up, char_down and space) are
132       generic font properties, and not necessarily a property of the text
133       that is set.
134
135       $gd_text->width('string')
136
137       Return the length of a string in pixels, without changing the current
138       value of the text.  Returns the width of 'string' rendered in the cur‐
139       rent font and size.  On failure, returns undef.
140
141       The use of this method is vaguely deprecated.
142
143       $gd_text->is_builtin
144
145       Returns true if the current object is based on a builtin GD font.
146
147       $gd_text->is_ttf
148
149       Returns true if the current object is based on a TrueType font.
150
151       $gd_text->can_do_ttf() or GD::Text->can_do_ttf()
152
153       Return true if this object can handle TTF fonts.
154
155       This depends on whether your version of GD is newer than 1.19 and has
156       TTF support compiled into it.
157
158       $gd_text->font_path(path_spec), GD::Text->font_path(path_spec)
159
160       This sets the font path for the class (i.e. not just for the object).
161       The "set_font" method will search this path to find the font specified
162       if it is a TrueType font. It should contain a list of paths. The cur‐
163       rent directory is always searched first, unless '.' is present in
164       FONT_PATH. Examples:
165
166         GD::Text->font_path('/usr/ttfonts'); # Unix
167         GD::Text->font_path('c:/fonts');     # MS-OS
168
169       Any font name that is not an absolute path will first be looked for in
170       the current directory, and then in /usr/ttfonts (c:\fonts).
171
172         GD::Text->font_path('/usr/ttfonts:.:lib/fonts'); # Unix
173         GD::Text->font_path('c:/fonts;.;f:/fonts');      # MS-OS
174
175       Any font name that is not an absolute path will first be looked for in
176       /usr/ttfonts (c:\fonts), then in the current directory. and then in
177       lib/fonts (f:\fonts), relative to the current directory.
178
179         GD::Text->font_path(undef);
180
181       Font files are only looked for in the current directory.
182
183       FONT_PATH is initialised at module load time from the environment vari‐
184       ables FONT_PATH or, if that's not present, TTF_FONT_PATH, or
185       TT_FONT_PATH.
186
187       Returns the value the font path is set to.  If called without arguments
188       "font_path" returns the current font path.
189
190       Note: This currently only works for unices, and (hopefully) for Micro‐
191       soft based OS's. If anyone feels the urge to have a look at the code,
192       and send me patches for their OS, I'd be most grateful)
193

BUGS

195       This module has only been tested with anglo-centric 'normal' fonts and
196       encodings.  Fonts that have other characteristics may not work well.
197       If that happens, please let me know how to make this work better.
198
199       The font height gets estimated by building a string with all printable
200       characters (with an ordinal value between 0 and 255) that pass the
201       POSIX::isprint() test (and not the isspace() test). If your system
202       doesn't have POSIX, I make an approximation that may be false. Under
203       Perl 5.8.0 the [[:print:]] character class is used, since the POSIX
204       is*() functions don't seem to work correctly.
205
206       The whole font path thing works well on Unix, but probably not very
207       well on other OS's. This is only a problem if you try to use a font
208       path. If you don't use a font path, there should never be a problem. I
209       will try to expand this in the future, but only if there's a demand for
210       it.  Suggestions welcome.
211

COPYRIGHT

213       copyright 1999 Martien Verbruggen (mgjv@comdyn.com.au)
214