From: Breno G. de Oliveira <garu@cpan.org>
Date: Mon, 7 Sep 2009 00:04:06 +0000 (-0300)
Subject: improved documentation
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=40654afe399356917d6406e4c20d7c2fe980074f;p=sdlgit%2FSDL_perl.git

improved documentation
---

diff --git a/lib/SDL/TTFont.pm b/lib/SDL/TTFont.pm
index d9b6e60..91d892e 100644
--- a/lib/SDL/TTFont.pm
+++ b/lib/SDL/TTFont.pm
@@ -182,19 +182,120 @@ croak "Could not initialize True Type Fonts\n"
 
 __END__;
 
-=pod
-
 =head1 NAME
 
 SDL::TTFont - a SDL perl extension
 
 =head1 SYNOPSIS
 
-  $font = new TTFont -name => "Utopia.ttf", -size => 18;
+  $font = SDL::TTFont->new( -name => "Utopia.ttf", -size => 18 );
 	
 =head1 DESCRIPTION
 
-L<SDL::TTFont> is a module for applying true type fonts to L<SDL::Surface>.
+L<< SDL::TTFont >> is a module for applying true type fonts to L<< SDL::Surface >>.
+
+=head1 METHODS
+
+=head2 new
+
+Instanciates a new font surface. It accepts the following parameters:
+
+=head3 -name
+
+=head3 -n
+
+The font filename (possibly with proper path) to be used. B<< This options is mandatory >>.
+
+=head3 -size
+
+=head3 -s
+
+The font size (height, in pixels) to be used. B<< This option is mandatory >>.
+
+=head3 -foreground
+
+=head3 -fg
+
+Foreground color for the font surface (i.e. the actual font color). It expects a 
+SDL::Color value. If omitted, black is used as font color.
+
+=head3 -background
+
+=head3 -bg
+
+Background color for the font surface (i.e. the font background color). It expects 
+a SDL::Color value. If omitted , white is used for the background.
+
+=head3 -mode
+
+=head3 -m
+
+Font mode. If omitted, SDL::TEXT_SHADED is used. Note that this class provides 
+human friendly accessors for setting different modes, so you should probably use 
+them instead. See below for further details.
+
+=head2 Text Modes
+
+The SDL::TTFont accepts three different types (shaded, solid, blended) for 
+three different encodings (text, utf8, unicode).
+
+  $font->text_shaded;       # sets mode to SDL::TEXT_SHADED
+  $font->text_solid;        # sets mode to SDL::TEXT_SOLID
+  $font->text_blended;      # sets mode to SDL::TEXT_BLENDED
+  
+  $font->utf8_shaded;       # sets mode to SDL::UTF8_SHADED
+  $font->utf8_solid;        # sets mode to SDL::UTF8_SOLID
+  $font->utf8_blended;      # sets mode to SDL::UTF8_BLENDED
+  
+  $font->unicode_shaded;    # sets mode to SDL::UNICODE_SHADED
+  $font->unicode_solid;     # sets mode to SDL::UNICODE_SOLID
+  $font->unicode_blended;   # sets mode to SDL::UNICODE_BLENDED
+
+=head2 Text Style
+
+You may also smoothly change your font style by calling any of the following 
+methods:
+
+  $font->normal;       # resets font styling, making text "normal"
+  $font->bold;         # sets bold style for font
+  $font->italic;       # sets italic style for font
+  $font->underline;    # sets underline style for font
+
+
+=head2 Ascent/Descent values
+
+Ascent is the number of pixels from the font baseline to the top of the font, while 
+descent is the number of pixels from the font baseline to the bottom of the font.
+
+  $font->ascent;      # height in pixels of the font ascent
+  $font->descent;     # height in pixels of the font descent
+
+=head2 height
+
+  my $height = $font->height;
+  
+Returns the height, in pixels, of the actual rendered text. This is the 
+average size for each glyph in the font.
+
+=head2 width(@text)
+
+  my $width = $font->width("Choose your destiny");
+
+Returns the dimensions needed to render the text. This can be used to help 
+determine the positioning needed for text before it is rendered. It can also 
+be used for wordwrapping and other layout effects.
+
+Be aware that most fonts - notably, non-monospaced ("ms") ones - use kerning 
+which adjusts the widths for specific letter pairs. For example, the width 
+for "ae" will not always match the width for "a" + "e".
+
+=head2 print ($surface, $top, $left, @text)
+
+Directly draws text to an existing surface. Receives the target L<< SDL::Surface >> 
+object and the relative top (y) and left (x) coordinates to put the text in. 
+The last parameter may be a string or an array or strings with the text to be 
+written.
+
 
 =head1 AUTHOR
 
@@ -202,6 +303,4 @@ David J. Goehrig
 
 =head1 SEE ALSO
 
-L<perl> L<SDL::Surface>
-
-=cut
+L<perl>, L<SDL>, L<< SDL::Surface >>