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).

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.

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.

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.