Home ··· Articles ··· Documentation ··· Dev ··· Irc ··· Download ··· About

Index


NAME

Top

SDLx::Text - SDL extension for manipulating text

CATEGORY

Top

Extension

SYNOPSIS

Top

    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

Top

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

Top

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',
            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 "http://search.cpan.org/perldoc?" for more information).

ACCESSORS

Top

All accessors below can be used to get and set their respective attributes. For example:

   my $font_name = $self->font;     # gets the font filename
   $self->font( 'somefont.ttf' );   # sets a new font

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.

y

Gets/sets the top (y) positioning of the text to be rendered, relative to whatever surface you are placing it into.

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.

METHODS

Top

text( $some_text )

Sets the text to be displayed by the SDLx::Text object. Return the SDLx::Text object itself, so you can easily chain this method around.

    my $obj = SDLx::Text->new->text( "Hello, Dave." );

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

Top

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 http://search.cpan.org/perldoc? 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.

ERRORS AND DIAGNOSTICS

Top

* "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

Top

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

Top

You can find documentation for this module with the perldoc command.

    perldoc SDLx::Text




AUTHORS

Top

COPYRIGHT & LICENSE

Top

SEE ALSO

Top

©2009. designed by FROGGS, hosted by mst, maintained by kthakore