PageRenderTime 35ms CodeModel.GetById 27ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 1ms

/lib/pods/SDLx/Text.pod

http://github.com/PerlGameDev/SDL
Unknown | 282 lines | 169 code | 113 blank | 0 comment | 0 complexity | 164c7848dd8741b42a2aebac6dbe113c MD5 | raw file
  1
  2=pod
  3
  4=head1 NAME
  5
  6SDLx::Text - SDL extension for manipulating text
  7
  8=head1 CATEGORY
  9
 10Extension
 11
 12=head1 SYNOPSIS
 13
 14    use SDL;
 15    use SDLx::App; 
 16    use SDLx::Text;
 17    
 18    my $app = SDLx::App->new;
 19
 20    my $message = SDLx::Text->new;
 21
 22    $message->write_to( $app, "Hello, World!" );
 23    $app->update;
 24
 25
 26=head1 DESCRIPTION
 27
 28The standard SDL API for handling fonts and rendering text is full of quirks
 29and and low-level functions scattered all over the place. This is a sugar
 30layer meant to let you easily handle text in your SDL apps.
 31
 32=head1 CONSTRUCTION
 33
 34=head2 new
 35
 36=head2 new ( %attributes )
 37
 38Instantiates a new SDLx::Text object. All attributes are optional:
 39
 40    my $text = SDLx::Text->new(
 41            font    => '/path/to/my/font.ttf',
 42            color   => [255, 255, 255], # "white"
 43            size    => 24,
 44            x       => 0,
 45            y       => 0,
 46            h_align => 'left',
 47            shadow  => 1,
 48            bold    => 1,
 49            text    => 'All your base are belong to us.'
 50    );
 51
 52Please check the accessors below for more information on each attribute.
 53All values shown above are the B<default values>, except for "text",
 54which defaults to C<undef>; and "font", which if not provided will load
 55the C<Gentium Basic> free font (see "L</"COPYRIGHT & LICENSE">" for more
 56information).
 57
 58=head1 ACCESSORS
 59
 60All accessors below can be used to get and set their respective attributes.
 61For example:
 62
 63   my $font_size = $obj->size;   # gets the font size
 64   $obj->size( 42 );             # sets a new font size
 65
 66Unless otherwise noticed, all accessors return their current value, after being set.
 67
 68=head2 x
 69
 70Gets/sets the left (x) positioning of the text to be rendered, relative
 71to whatever surface you are placing it into. Note that if you set the
 72C<h_align> property to anything other than 'C<left>', the text might
 73not start exactly where you set C<x> to be, but relative to that value.
 74
 75Default value is 0, meaning leftmost corner.
 76
 77=head2 y
 78
 79Gets/sets the top (y) positioning of the text to be rendered, relative
 80to whatever surface you are placing it into.
 81
 82Default value is 0, meaning top.
 83
 84=head2 h_align
 85
 86Gets/sets the horizontal alignment of the text to be rendered relative to
 87whatever surface you are placing it into. Available alignments are 'C<left>',
 88'C<right>' and 'C<center>'. Default is 'C<left>'.
 89
 90=head2 color
 91
 92Gets/sets the text color. The color is an array reference in C<[R, G, B]> or C<[R, G, B, A]> format. See L<SDL::Color> for more information on colors.
 93
 94=head2 size
 95
 96Gets/sets the font size.
 97
 98=head2 font
 99
100Pass it a string containing the path to your desired font to use it. Fonts
101can be in TTF, OTF or FON formats. Generates an exception if the font
102cannot be loaded.
103
104Returns the L<SDL::TTF::Font> object representing the font.
105
106=head2 shadow
107
108Set this to true to create a nice 3D shadow effect on the rendered text.
109This is achieved by creating another version of the text below the
110original one, at a given offset.
111
112=head2 shadow_color
113
114Set the RGB color array for the shadow. Defaults to black ( C<[0,0,0]> ).
115
116=head2 shadow_offset
117
118Sets the offset in which to display the shadow. Defaults to 1, meaning
1191 pixel below and 1 pixel to the right of the original text.
120
121=head2 Setting the Font Style
122
123The following accessors can be used to set a rendering file for the B<loaded> font.
124They will only work for the current font, so if you change fonts, make sure to
125apply your modifiers again. A single font can have more than one modifier applied to it, eg:
126
127  my $text = SDLx::Text->new;
128
129  $text->bold(1);
130  $text->italic(1);
131
132Set them to a true value to enable, false to disable.
133
134=head3 normal
135
136Sets the font style to normal.
137
138=head3 bold
139
140Sets the font style to bold.
141
142=head3 italic
143
144Sets the font style to italic.
145
146=head3 underline
147
148Sets the font style to underline.
149
150B<Note>: Due to libSDL design and depending on the chosen font, sometimes
151the underline may be outside of the generated text surface, and thus not
152visible when blitted to the screen. In these cases, you should probably turn
153off the option and draw your own underlines in the target surface.
154
155=head3 strikethrough
156
157Sets the font style to strikethrough.
158
159B<Note>: Due to libSDL design and depending on the chosen font, sometimes
160the strikethrough may be outside of the generated text surface, and thus not
161visible when blitted to the screen. In these cases, you should probably turn
162off the option and draw your own strikethroughs in the target surface.
163
164=head1 METHODS
165
166=head2 text( $some_text )
167
168Sets the text to be displayed by the SDLx::Text object. If you call it
169without any arguments, you'll get the current text string:
170
171   my $string = $obj->text();
172
173Otherwise, C<text()> will return the SDLx::Text object itself, so you can
174easily chain this method around.
175
176    my $obj = SDLx::Text->new->text( "Hello, Dave." );
177
178Note that this will happen even if it's an empty string, or undef.
179B<You pass an argument, you get an object>.
180
181Text will always be rendered as utf8, so you can pass any string containing
182regular ASCII or valid utf8 characters.
183
184=head2 write_to( $target_surface )
185
186=head2 write_to( $target_surface, "text to write" )
187
188Renders the text onto C<$target_surface> (usually the app itself). The
189text string may be passed as a parameter, otherwise it will use whatever
190is already set (via the C<new()> or C<text()> methods.
191
192=head2 write_xy( $target_surface, $x, $y )
193
194=head2 write_xy( $target_surface, $x, $y, $text )
195
196Same as C<write_to()>, but will render the text using the given top (y) and
197left (x) coordinates.
198
199
200=head1 READ-ONLY ATTRIBUTES
201
202As you set or update your text, font or size, SDLx::Text updates the surface
203that represents it. You don't usually need to worry about this at all, and
204we strongly recommend you use the L<"/METHODS"> above to render your text.
205
206If however you need to know how tall or wide the rendered text will be
207(in pixels), or if you want to retrieve the surface so you can manipulate and
208render it yourself, you can use the following getters:
209
210=head2 surface
211
212Returns the underlying surface representing the text itself. You probably don't need this, unless you're doing something really funky.
213
214=head2 w
215
216Shortcut to see the width of the underlying surface representing the text.
217
218=head2 h
219
220Shortcut to see the height of the underlying surface representing the text.
221
222=head2 font_filename
223
224Returns the file name for the loaded font. Use C<font()> to get the font object itself, or to set a new font.
225
226=head1 ERRORS AND DIAGNOSTICS
227
228=over 4
229
230=item * "SDL_ttf support has not been compiled"
231
232In order to render text in SDL you must have enabled SDL_ttf while building L<Alien::SDL>.
233
234=item * "Cannot init TTF: <some error>"
235
236In order to load fonts and render text, we need to initialize L<SDL::TTF>
237- that is, in case it hasn't been initialized already. The error above will
238appear in the rare event of any problem during initialization.
239
240=item * "Error opening font: <some error>"
241
242The font file you set either via C<< font( 'font.ttf' ) >> or during
243construction could not be loaded. The file may not exist in the given path,
244have wrong permissions, be corrupted, or of an unsupported format. Please
245refer the C<< <some error> >> message in the message itself for further
246information.
247
248=item * "TTF rendering error: <some error>"
249
250When you call C<text()>, it renders the provided string onto an internal
251L<SDL::Surface> object. If there was any problem rendering the text, this
252message will appear.
253
254=back
255
256=head1 BUGS
257
258Please report any bugs or feature requests to the bug tracker. We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.
259
260
261=head1 SUPPORT
262
263You can find documentation for this module with the perldoc command.
264
265    perldoc SDLx::Text
266
267
268=head1 AUTHORS
269
270See L<SDL/AUTHORS>.
271
272
273=head1 COPYRIGHT & LICENSE
274
275This program is free software; you can redistribute it and/or modify it
276under the same terms as Perl itself.
277
278This module ships with a default font, "I<Gentium Basic>", Copyright 2003-2008 SIL International (http://sil.org), released under the SIL Open Font License 1.1 (OFL). The font is available for use in free and commercial products, with some minor restrictions. Please read the C<OFL.txt> and C<OFL-FAQ.txt> for further information.
279
280=head1 SEE ALSO
281
282L<SDL>, L<SDLx::App>, L<SDL::TTF>