1SDLx::Text(3) User Contributed Perl Documentation SDLx::Text(3)
2
6 SDLx::Text - SDL extension for manipulating text
7
9 Extension
10
12 use SDL;
13 use SDLx::App;
14 use SDLx::Text;
15 my $app = SDLx::App->new;
17 my $message = SDLx::Text->new;
19 $message->write_to( $app, "Hello, World!" );
21 $app->update;
22
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
29 new
30 new ( %attributes )
31 Instantiates a new SDLx::Text object. All attributes are optional:
32 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 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
52 All accessors below can be used to get and set their respective
53 attributes. For example:
54 my $font_size = $obj->size; # gets the font size
56 $obj->size( 42 ); # sets a new font size
57 Unless otherwise noticed, all accessors return their current value,
59 after being set.
60 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 Default value is 0, meaning leftmost corner.
68 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 Default value is 0, meaning top.
74 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 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 size
86 Gets/sets the font size.
87 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 Returns the SDL::TTF::Font object representing the font.
94 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 shadow_color
101 Set the RGB color array for the shadow. Defaults to black ( "[0,0,0]"
102 ).
103 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 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 my $text = SDLx::Text->new;
115 $text->bold(1);
117 $text->italic(1);
118 Set them to a true value to enable, false to disable.
120 normal
122 Sets the font style to normal.
124 bold
126 Sets the font style to bold.
128 italic
130 Sets the font style to italic.
132 underline
134 Sets the font style to underline.
136 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 strikethrough
144 Sets the font style to strikethrough.
146 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
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 my $string = $obj->text();
159 Otherwise, "text()" will return the SDLx::Text object itself, so you
161 can easily chain this method around.
162 my $obj = SDLx::Text->new->text( "Hello, Dave." );
164 Note that this will happen even if it's an empty string, or undef. You
166 pass an argument, you get an object.
167 Text will always be rendered as utf8, so you can pass any string
169 containing regular ASCII or valid utf8 characters.
170 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 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
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 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 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 w
197 Shortcut to see the width of the underlying surface representing the
198 text.
199 h
201 Shortcut to see the height of the underlying surface representing the
202 text.
203 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
209 • "SDL_ttf support has not been compiled"
210 In order to render text in SDL you must have enabled SDL_ttf while
212 building Alien::SDL.
213 • "Cannot init TTF: <some error>"
215 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 • "Error opening font: <some error>"
222 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 • "TTF rendering error: <some error>"
230 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
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
241 You can find documentation for this module with the perldoc command.
242 perldoc SDLx::Text
244
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 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
259 SDL, SDLx::App, SDL::TTF
260perl v5.34.0 2022-01-21 SDLx::Text(3)