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
40       module, 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
47       ("gdTinyFont", "gdGiantFont"), you will need to "use" the GD module as
48       well as one the GD::Text modules, because it is GD that exports those
49       names into your name space. If you don't like that, use the longer
50       alternatives ("GD::Font-"Giant>) instead.
51

METHODS

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

BUGS

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

SEE ALSO

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

POD ERRORS

208       Hey! The above document had some coding errors, which are explained
209       below:
210
211       Around line 197:
212           =pod directives shouldn't be over one line long!  Ignoring all 20
213           lines of content
214
215
216
217perl v5.30.1                      2020-01-30                           Text(3)
Impressum