lib/docs/TTFont.pod

   1 =head1 NAME
   2
   3 SDL::TTFont - a SDL perl extension
   4
   5 =head1 SYNOPSIS
   6
   7   $font = SDL::TTFont->new( -name => "Utopia.ttf", -size => 18 );
   8
   9 =head1 DESCRIPTION
  10
  11 L<< SDL::TTFont >> is a module for applying true type fonts to L<< SDL::Surface >>.
  12
  13 =head1 METHODS
  14
  15 =head2 new
  16
  17 Instanciates a new font surface. It accepts the following parameters:
  18
  19 =head3 -name
  20
  21 =head3 -n
  22
  23 The font filename (possibly with proper path) to be used. B<< This options is mandatory >>.
  24
  25 =head3 -size
  26
  27 =head3 -s
  28
  29 The font size (height, in pixels) to be used. B<< This option is mandatory >>.
  30
  31 =head3 -foreground
  32
  33 =head3 -fg
  34
  35 Foreground color for the font surface (i.e. the actual font color). It expects a
  36 SDL::Color value. If omitted, black is used as font color.
  37
  38 =head3 -background
  39
  40 =head3 -bg
  41
  42 Background color for the font surface (i.e. the font background color). It expects
  43 a SDL::Color value. If omitted , white is used for the background.
  44
  45 =head3 -mode
  46
  47 =head3 -m
  48
  49 Font mode. If omitted, SDL::TEXT_SHADED is used. Note that this class provides
  50 human friendly accessors for setting different modes, so you should probably use
  51 them instead. See below for further details.
  52
  53 =head2 Text Modes
  54
  55 The SDL::TTFont accepts three different types (shaded, solid, blended) for
  56 three different encodings (text, utf8, unicode).
  57
  58   $font->text_shaded;       # sets mode to SDL::TEXT_SHADED
  59   $font->text_solid;        # sets mode to SDL::TEXT_SOLID
  60   $font->text_blended;      # sets mode to SDL::TEXT_BLENDED
  61
  62   $font->utf8_shaded;       # sets mode to SDL::UTF8_SHADED
  63   $font->utf8_solid;        # sets mode to SDL::UTF8_SOLID
  64   $font->utf8_blended;      # sets mode to SDL::UTF8_BLENDED
  65
  66   $font->unicode_shaded;    # sets mode to SDL::UNICODE_SHADED
  67   $font->unicode_solid;     # sets mode to SDL::UNICODE_SOLID
  68   $font->unicode_blended;   # sets mode to SDL::UNICODE_BLENDED
  69
  70 =head2 Text Style
  71
  72 You may also smoothly change your font style by calling any of the following
  73 methods:
  74
  75   $font->normal;       # resets font styling, making text "normal"
  76   $font->bold;         # sets bold style for font
  77   $font->italic;       # sets italic style for font
  78   $font->underline;    # sets underline style for font
  79
  80
  81 =head2 Ascent/Descent values
  82
  83 Ascent is the number of pixels from the font baseline to the top of the font, while
  84 descent is the number of pixels from the font baseline to the bottom of the font.
  85
  86   $font->ascent;      # height in pixels of the font ascent
  87   $font->descent;     # height in pixels of the font descent
  88
  89 =head2 height
  90
  91   my $height = $font->height;
  92
  93 Returns the height, in pixels, of the actual rendered text. This is the
  94 average size for each glyph in the font.
  95
  96 =head2 width(@text)
  97
  98   my $width = $font->width("Choose your destiny");
  99
 100 Returns the dimensions needed to render the text. This can be used to help
 101 determine the positioning needed for text before it is rendered. It can also
 102 be used for wordwrapping and other layout effects.
 103
 104 Be aware that most fonts - notably, non-monospaced ("ms") ones - use kerning
 105 which adjusts the widths for specific letter pairs. For example, the width
 106 for "ae" will not always match the width for "a" + "e".
 107
 108 =head2 print ($surface, $top, $left, @text)
 109
 110 Directly draws text to an existing surface. Receives the target L<< SDL::Surface >>
 111 object and the relative top (y) and left (x) coordinates to put the text in.
 112 The last parameter may be a string or an array or strings with the text to be
 113 written.
 114
 115
 116 =head1 AUTHOR
 117
 118 David J. Goehrig
 119
 120 =head1 SEE ALSO
 121
 122 L<perl>, L<SDL>, L<< SDL::Surface >>