1SDLx::Text(3)         User Contributed Perl Documentation        SDLx::Text(3)
2
3
4

NAME

6       SDLx::Text - SDL extension for manipulating text
7

CATEGORY

9       Extension
10

SYNOPSIS

12           use SDL;
13           use SDLx::App;
14           use SDLx::Text;
15
16           my $app = SDLx::App->new;
17
18           my $message = SDLx::Text->new;
19
20           $message->write_to( $app, "Hello, World!" );
21           $app->update;
22

DESCRIPTION

24       The standard SDL API for handling fonts and rendering text is full of
25       quirks and and low-level functions scattered all over the place. This
26       is a sugar layer meant to let you easily handle text in your SDL apps.
27

CONSTRUCTION

29   new
30   new ( %attributes )
31       Instantiates a new SDLx::Text object. All attributes are optional:
32
33           my $text = SDLx::Text->new(
34                   font    => '/path/to/my/font.ttf',
35                   color   => [255, 255, 255], # "white"
36                   size    => 24,
37                   x       => 0,
38                   y       => 0,
39                   h_align => 'left',
40                   shadow  => 1,
41                   bold    => 1,
42                   text    => 'All your base are belong to us.'
43           );
44
45       Please check the accessors below for more information on each
46       attribute.  All values shown above are the default values, except for
47       "text", which defaults to "undef"; and "font", which if not provided
48       will load the "Gentium Basic" free font (see ""COPYRIGHT & LICENSE""
49       for more information).
50

ACCESSORS

52       All accessors below can be used to get and set their respective
53       attributes.  For example:
54
55          my $font_size = $obj->size;   # gets the font size
56          $obj->size( 42 );             # sets a new font size
57
58       Unless otherwise noticed, all accessors return their current value,
59       after being set.
60
61   x
62       Gets/sets the left (x) positioning of the text to be rendered, relative
63       to whatever surface you are placing it into. Note that if you set the
64       "h_align" property to anything other than '"left"', the text might not
65       start exactly where you set "x" to be, but relative to that value.
66
67       Default value is 0, meaning leftmost corner.
68
69   y
70       Gets/sets the top (y) positioning of the text to be rendered, relative
71       to whatever surface you are placing it into.
72
73       Default value is 0, meaning top.
74
75   h_align
76       Gets/sets the horizontal alignment of the text to be rendered relative
77       to whatever surface you are placing it into. Available alignments are
78       '"left"', '"right"' and '"center"'. Default is '"left"'.
79
80   color
81       Gets/sets the text color. The color is an array reference in "[R, G,
82       B]" or "[R, G, B, A]" format. See SDL::Color for more information on
83       colors.
84
85   size
86       Gets/sets the font size.
87
88   font
89       Pass it a string containing the path to your desired font to use it.
90       Fonts can be in TTF, OTF or FON formats. Generates an exception if the
91       font cannot be loaded.
92
93       Returns the SDL::TTF::Font object representing the font.
94
95   shadow
96       Set this to true to create a nice 3D shadow effect on the rendered
97       text.  This is achieved by creating another version of the text below
98       the original one, at a given offset.
99
100   shadow_color
101       Set the RGB color array for the shadow. Defaults to black ( "[0,0,0]"
102       ).
103
104   shadow_offset
105       Sets the offset in which to display the shadow. Defaults to 1, meaning
106       1 pixel below and 1 pixel to the right of the original text.
107
108   Setting the Font Style
109       The following accessors can be used to set a rendering file for the
110       loaded font.  They will only work for the current font, so if you
111       change fonts, make sure to apply your modifiers again. A single font
112       can have more than one modifier applied to it, eg:
113
114         my $text = SDLx::Text->new;
115
116         $text->bold(1);
117         $text->italic(1);
118
119       Set them to a true value to enable, false to disable.
120
121       normal
122
123       Sets the font style to normal.
124
125       bold
126
127       Sets the font style to bold.
128
129       italic
130
131       Sets the font style to italic.
132
133       underline
134
135       Sets the font style to underline.
136
137       Note: Due to libSDL design and depending on the chosen font, sometimes
138       the underline may be outside of the generated text surface, and thus
139       not visible when blitted to the screen. In these cases, you should
140       probably turn off the option and draw your own underlines in the target
141       surface.
142
143       strikethrough
144
145       Sets the font style to strikethrough.
146
147       Note: Due to libSDL design and depending on the chosen font, sometimes
148       the strikethrough may be outside of the generated text surface, and
149       thus not visible when blitted to the screen. In these cases, you should
150       probably turn off the option and draw your own strikethroughs in the
151       target surface.
152

METHODS

154   text( $some_text )
155       Sets the text to be displayed by the SDLx::Text object. If you call it
156       without any arguments, you'll get the current text string:
157
158          my $string = $obj->text();
159
160       Otherwise, "text()" will return the SDLx::Text object itself, so you
161       can easily chain this method around.
162
163           my $obj = SDLx::Text->new->text( "Hello, Dave." );
164
165       Note that this will happen even if it's an empty string, or undef.  You
166       pass an argument, you get an object.
167
168       Text will always be rendered as utf8, so you can pass any string
169       containing regular ASCII or valid utf8 characters.
170
171   write_to( $target_surface )
172   write_to( $target_surface, "text to write" )
173       Renders the text onto $target_surface (usually the app itself). The
174       text string may be passed as a parameter, otherwise it will use
175       whatever is already set (via the "new()" or "text()" methods.
176
177   write_xy( $target_surface, $x, $y )
178   write_xy( $target_surface, $x, $y, $text )
179       Same as "write_to()", but will render the text using the given top (y)
180       and left (x) coordinates.
181

READ-ONLY ATTRIBUTES

183       As you set or update your text, font or size, SDLx::Text updates the
184       surface that represents it. You don't usually need to worry about this
185       at all, and we strongly recommend you use the "METHODS"" in " above to
186       render your text.
187
188       If however you need to know how tall or wide the rendered text will be
189       (in pixels), or if you want to retrieve the surface so you can
190       manipulate and render it yourself, you can use the following getters:
191
192   surface
193       Returns the underlying surface representing the text itself. You
194       probably don't need this, unless you're doing something really funky.
195
196   w
197       Shortcut to see the width of the underlying surface representing the
198       text.
199
200   h
201       Shortcut to see the height of the underlying surface representing the
202       text.
203
204   font_filename
205       Returns the file name for the loaded font. Use "font()" to get the font
206       object itself, or to set a new font.
207

ERRORS AND DIAGNOSTICS

209       •   "SDL_ttf support has not been compiled"
210
211           In order to render text in SDL you must have enabled SDL_ttf while
212           building Alien::SDL.
213
214       •   "Cannot init TTF: <some error>"
215
216           In order to load fonts and render text, we need to initialize
217           SDL::TTF - that is, in case it hasn't been initialized already. The
218           error above will appear in the rare event of any problem during
219           initialization.
220
221       •   "Error opening font: <some error>"
222
223           The font file you set either via "font( 'font.ttf' )" or during
224           construction could not be loaded. The file may not exist in the
225           given path, have wrong permissions, be corrupted, or of an
226           unsupported format. Please refer the "<some error>" message in the
227           message itself for further information.
228
229       •   "TTF rendering error: <some error>"
230
231           When you call "text()", it renders the provided string onto an
232           internal SDL::Surface object. If there was any problem rendering
233           the text, this message will appear.
234

BUGS

236       Please report any bugs or feature requests to the bug tracker. We will
237       be notified, and then you'll automatically be notified of progress on
238       your bug as we make changes.
239

SUPPORT

241       You can find documentation for this module with the perldoc command.
242
243           perldoc SDLx::Text
244

AUTHORS

246       See "AUTHORS" in SDL.
247
249       This program is free software; you can redistribute it and/or modify it
250       under the same terms as Perl itself.
251
252       This module ships with a default font, "Gentium Basic", Copyright
253       2003-2008 SIL International (http://sil.org), released under the SIL
254       Open Font License 1.1 (OFL). The font is available for use in free and
255       commercial products, with some minor restrictions. Please read the
256       "OFL.txt" and "OFL-FAQ.txt" for further information.
257

SEE ALSO

259       SDL, SDLx::App, SDL::TTF
260
261
262
263perl v5.34.0                      2021-07-22                     SDLx::Text(3)
Impressum