pods::SDLx::Text(3) User Contributed Perl Documentation pods::SDLx::Text(3)NAME
SDLx::Text - SDL extension for manipulating text
CATEGORY
Extension
SYNOPSIS
use SDL;
use SDLx::App;
use SDLx::Text;
my $app = SDLx::App->new;
my $message = SDLx::Text->new;
$message->write_to( $app, "Hello, World!" );
$app->update;
DESCRIPTION
The standard SDL API for handling fonts and rendering text is full of
quirks and and low-level functions scattered all over the place. This
is a sugar layer meant to let you easily handle text in your SDL apps.
CONSTRUCTION
new
new ( %attributes )
Instantiates a new SDLx::Text object. All attributes are optional:
my $text = SDLx::Text->new(
font => '/path/to/my/font.ttf',
color => [255, 255, 255], # "white"
size => 24,
x => 0,
y => 0,
h_align => 'left',
shadow => 1,
bold => 1,
text => 'All your base are belong to us.'
);
Please check the accessors below for more information on each
attribute. All values shown above are the default values, except for
"text", which defaults to "undef"; and "font", which if not provided
will load the "Gentium Basic" free font (see ""COPYRIGHT & LICENSE""
for more information).
ACCESSORS
All accessors below can be used to get and set their respective
attributes. For example:
my $font_size = $obj->size; # gets the font size
$obj->size( 42 ); # sets a new font size
Unless otherwise noticed, all accessors return their current value,
after being set.
x
Gets/sets the left (x) positioning of the text to be rendered, relative
to whatever surface you are placing it into. Note that if you set the
"h_align" property to anything other than '"left"', the text might not
start exactly where you set "x" to be, but relative to that value.
Default value is 0, meaning leftmost corner.
y
Gets/sets the top (y) positioning of the text to be rendered, relative
to whatever surface you are placing it into.
Default value is 0, meaning top.
h_align
Gets/sets the horizontal alignment of the text to be rendered relative
to whatever surface you are placing it into. Available alignments are
'"left"', '"right"' and '"center"'. Default is '"left"'.
color
Gets/sets the text color. The color is an array reference in "[R, G,
B]" or "[R, G, B, A]" format. See SDL::Color for more information on
colors.
size
Gets/sets the font size.
font
Pass it a string containing the path to your desired font to use it.
Fonts can be in TTF, OTF or FON formats. Generates an exception if the
font cannot be loaded.
Returns the SDL::TTF::Font object representing the font.
shadow
Set this to true to create a nice 3D shadow effect on the rendered
text. This is achieved by creating another version of the text below
the original one, at a given offset.
shadow_color
Set the RGB color array for the shadow. Defaults to black ( "[0,0,0]"
).
shadow_offset
Sets the offset in which to display the shadow. Defaults to 1, meaning
1 pixel below and 1 pixel to the right of the original text.
Setting the Font Style
The following accessors can be used to set a rendering file for the
loaded font. They will only work for the current font, so if you
change fonts, make sure to apply your modifiers again. A single font
can have more than one modifier applied to it, eg:
my $text = SDLx::Text->new;
$text->bold(1);
$text->italic(1);
Set them to a true value to enable, false to disable.
normal
Sets the font style to normal.
bold
Sets the font style to bold.
italic
Sets the font style to italic.
underline
Sets the font style to underline.
Note: Due to libSDL design and depending on the chosen font, sometimes
the underline may be outside of the generated text surface, and thus
not visible when blitted to the screen. In these cases, you should
probably turn off the option and draw your own underlines in the target
surface.
strikethrough
Sets the font style to strikethrough.
Note: Due to libSDL design and depending on the chosen font, sometimes
the strikethrough may be outside of the generated text surface, and
thus not visible when blitted to the screen. In these cases, you should
probably turn off the option and draw your own strikethroughs in the
target surface.
METHODS
text( $some_text )
Sets the text to be displayed by the SDLx::Text object. If you call it
without any arguments, you'll get the current text string:
my $string = $obj->text();
Otherwise, "text()" will return the SDLx::Text object itself, so you
can easily chain this method around.
my $obj = SDLx::Text->new->text( "Hello, Dave." );
Note that this will happen even if it's an empty string, or undef. You
pass an argument, you get an object.
Text will always be rendered as utf8, so you can pass any string
containing regular ASCII or valid utf8 characters.
write_to( $target_surface )
write_to( $target_surface, "text to write" )
Renders the text onto $target_surface (usually the app itself). The
text string may be passed as a parameter, otherwise it will use
whatever is already set (via the "new()" or "text()" methods.
write_xy( $target_surface, $x, $y )
write_xy( $target_surface, $x, $y, $text )
Same as "write_to()", but will render the text using the given top (y)
and left (x) coordinates.
READ-ONLY ATTRIBUTES
As you set or update your text, font or size, SDLx::Text updates the
surface that represents it. You don't usually need to worry about this
at all, and we strongly recommend you use the "METHODS"" in " above to
render your text.
If however you need to know how tall or wide the rendered text will be
(in pixels), or if you want to retrieve the surface so you can
manipulate and render it yourself, you can use the following getters:
surface
Returns the underlying surface representing the text itself. You
probably don't need this, unless you're doing something really funky.
w
Shortcut to see the width of the underlying surface representing the
text.
h
Shortcut to see the height of the underlying surface representing the
text.
font_filename
Returns the file name for the loaded font. Use "font()" to get the font
object itself, or to set a new font.
ERRORS AND DIAGNOSTICS
· "SDL_ttf support has not been compiled"
In order to render text in SDL you must have enabled SDL_ttf while
building Alien::SDL.
· "Cannot init TTF: <some error>"
In order to load fonts and render text, we need to initialize
SDL::TTF - that is, in case it hasn't been initialized already. The
error above will appear in the rare event of any problem during
initialization.
· "Error opening font: <some error>"
The font file you set either via "font( 'font.ttf' )" or during
construction could not be loaded. The file may not exist in the
given path, have wrong permissions, be corrupted, or of an
unsupported format. Please refer the "<some error>" message in the
message itself for further information.
· "TTF rendering error: <some error>"
When you call "text()", it renders the provided string onto an
internal SDL::Surface object. If there was any problem rendering
the text, this message will appear.
BUGS
Please 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.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc SDLx::Text
AUTHORS
See "AUTHORS" in SDL.
COPYRIGHT & LICENSE
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
This module ships with a default font, "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
"OFL.txt" and "OFL-FAQ.txt" for further information.
SEE ALSO
SDL, SDLx::App, SDL::TTF
perl v5.18.1 2013-09-28 pods::SDLx::Text(3)
