5 # Copyright (C) 2005 David J. Goehrig <dgoehrig@cpan.org>
7 # ------------------------------------------------------------------------------
9 # This library is free software; you can redistribute it and/or
10 # modify it under the terms of the GNU Lesser General Public
11 # License as published by the Free Software Foundation; either
12 # version 2.1 of the License, or (at your option) any later version.
14 # This library is distributed in the hope that it will be useful,
15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 # Lesser General Public License for more details.
19 # You should have received a copy of the GNU Lesser General Public
20 # License along with this library; if not, write to the Free Software
21 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
23 # ------------------------------------------------------------------------------
25 # Please feel free to send questions, suggestions or improvements to:
41 @ISA = qw(SDL::Surface);
45 my $class = ref($proto) || $proto;
49 $self->{-mode} = $options{-mode} || $options{-m} || SDL::TEXT_SHADED();
50 $self->{-name} = $options{-name} || $options{-n};
51 $self->{-size} = $options{-size} || $options{-s};
52 $self->{-fg} = $options{-foreground} || $options{-fg} || $SDL::Color::black;
53 $self->{-bg} = $options{-background} || $options{-bg} || $SDL::Color::white;
55 croak "SDL::TTFont::new requires a -name\n"
56 unless ($$self{-name});
58 croak "SDL::TTFont::new requires a -size\n"
59 unless ($$self{-size});
61 $self->{-font} = SDL::TTFOpenFont($self->{-name},$self->{-size});
63 croak "Could not open font $$self{-name}, ", SDL::GetError(), "\n"
64 unless ($self->{-font});
72 SDL::FreeSurface($self->{-surface}) if (defined ($self->{-surface}));
73 SDL::TTFCloseFont($self->{-font}) if (defined ($self->{-font}));
77 my ($self,$surface,$x,$y,@text) = @_;
79 croak "Print requies an SDL::Surface"
80 unless( ref($surface) && $surface->isa("SDL::Surface") );
82 SDL::FreeSurface($self->{-surface}) if ($$self{-surface});
84 $$self{-surface} = SDL::TTFPutString($$self{-font},$$self{-mode},
85 $$surface,$x,$y,$self->{-fg},$self->{-bg},join("",@text));
87 croak "Could not print \"", join("",@text), "\" to surface, ",
88 SDL::GetError(), "\n" unless ($$self{-surface});
92 my ($self,@text) = @_;
93 my $aref = SDL::TTFSizeText($$self{-font},join(" ",@text));
99 SDL::TTFFontHeight($$self{-font});
104 SDL::TTFFontAscent($$self{-font});
109 SDL::TTFFontDescent($$self{-font});
114 SDL::TTFSetFontStyle($$self{-font},SDL::TTF_STYLE_NORMAL());
119 SDL::TTFSetFontStyle($$self{-font},SDL::TTF_STYLE_BOLD());
124 SDL::TTFSetFontStyle($$self{-font},SDL::TTF_STYLE_ITALIC());
130 SDL::TTFSetFontStyle($$self{-font},SDL::TTF_STYLE_UNDERLINE());
135 $$self{-mode} = SDL::TEXT_SHADED();
140 $$self{-mode} = SDL::TEXT_SOLID();
145 $$self{-mode} = SDL::TEXT_BLENDED();
150 $$self{-mode} = SDL::UTF8_SHADED();
155 $$self{-mode} = SDL::UTF8_SOLID();
160 $$self{-mode} = SDL::UTF8_BLENDED();
165 $$self{-mode} = SDL::UNICODE_SHADED();
170 $$self{-mode} = SDL::UNICODE_SOLID();
173 sub unicode_blended {
175 $$self{-mode} = SDL::UNICODE_BLENDED();
178 croak "Could not initialize True Type Fonts\n"
179 if ( SDL::TTFInit() < 0);
187 SDL::TTFont - a SDL perl extension
191 $font = SDL::TTFont->new( -name => "Utopia.ttf", -size => 18 );
195 L<< SDL::TTFont >> is a module for applying true type fonts to L<< SDL::Surface >>.
201 Instanciates a new font surface. It accepts the following parameters:
207 The font filename (possibly with proper path) to be used. B<< This options is mandatory >>.
213 The font size (height, in pixels) to be used. B<< This option is mandatory >>.
219 Foreground color for the font surface (i.e. the actual font color). It expects a
220 SDL::Color value. If omitted, black is used as font color.
226 Background color for the font surface (i.e. the font background color). It expects
227 a SDL::Color value. If omitted , white is used for the background.
233 Font mode. If omitted, SDL::TEXT_SHADED is used. Note that this class provides
234 human friendly accessors for setting different modes, so you should probably use
235 them instead. See below for further details.
239 The SDL::TTFont accepts three different types (shaded, solid, blended) for
240 three different encodings (text, utf8, unicode).
242 $font->text_shaded; # sets mode to SDL::TEXT_SHADED
243 $font->text_solid; # sets mode to SDL::TEXT_SOLID
244 $font->text_blended; # sets mode to SDL::TEXT_BLENDED
246 $font->utf8_shaded; # sets mode to SDL::UTF8_SHADED
247 $font->utf8_solid; # sets mode to SDL::UTF8_SOLID
248 $font->utf8_blended; # sets mode to SDL::UTF8_BLENDED
250 $font->unicode_shaded; # sets mode to SDL::UNICODE_SHADED
251 $font->unicode_solid; # sets mode to SDL::UNICODE_SOLID
252 $font->unicode_blended; # sets mode to SDL::UNICODE_BLENDED
256 You may also smoothly change your font style by calling any of the following
259 $font->normal; # resets font styling, making text "normal"
260 $font->bold; # sets bold style for font
261 $font->italic; # sets italic style for font
262 $font->underline; # sets underline style for font
265 =head2 Ascent/Descent values
267 Ascent is the number of pixels from the font baseline to the top of the font, while
268 descent is the number of pixels from the font baseline to the bottom of the font.
270 $font->ascent; # height in pixels of the font ascent
271 $font->descent; # height in pixels of the font descent
275 my $height = $font->height;
277 Returns the height, in pixels, of the actual rendered text. This is the
278 average size for each glyph in the font.
282 my $width = $font->width("Choose your destiny");
284 Returns the dimensions needed to render the text. This can be used to help
285 determine the positioning needed for text before it is rendered. It can also
286 be used for wordwrapping and other layout effects.
288 Be aware that most fonts - notably, non-monospaced ("ms") ones - use kerning
289 which adjusts the widths for specific letter pairs. For example, the width
290 for "ae" will not always match the width for "a" + "e".
292 =head2 print ($surface, $top, $left, @text)
294 Directly draws text to an existing surface. Receives the target L<< SDL::Surface >>
295 object and the relative top (y) and left (x) coordinates to put the text in.
296 The last parameter may be a string or an array or strings with the text to be
306 L<perl>, L<SDL>, L<< SDL::Surface >>