Commit | Line | Data |
fcf60e89 |
1 | <div class="pod"> |
2 | <!-- INDEX START --> |
3 | <h3 id="TOP">Index</h3> |
4 | |
5 | <ul><li><a href="#NAME">NAME</a></li> |
6 | <li><a href="#CATEGORY">CATEGORY</a></li> |
7 | <li><a href="#SYNOPSIS">SYNOPSIS</a></li> |
8 | <li><a href="#DESCRIPTION">DESCRIPTION</a></li> |
9 | <li><a href="#CONSTRUCTION">CONSTRUCTION</a> |
10 | <ul><li><a href="#new">new</a></li> |
11 | <li><a href="#new_attributes">new ( %attributes )</a></li> |
12 | </ul> |
13 | </li> |
14 | <li><a href="#ACCESSORS">ACCESSORS</a> |
15 | <ul><li><a href="#x">x</a></li> |
16 | <li><a href="#y">y</a></li> |
17 | <li><a href="#h_align">h_align</a></li> |
18 | <li><a href="#color">color</a></li> |
19 | <li><a href="#size">size</a></li> |
20 | <li><a href="#font">font</a></li> |
21 | </ul> |
22 | </li> |
23 | <li><a href="#METHODS">METHODS</a> |
24 | <ul><li><a href="#text_some_text">text( $some_text )</a></li> |
25 | <li><a href="#write_to_target_surface">write_to( $target_surface )</a></li> |
26 | <li><a href="#write_to_target_surface_quot_text_to">write_to( $target_surface, "text to write" )</a></li> |
27 | <li><a href="#write_xy_target_surface_x_y">write_xy( $target_surface, $x, $y )</a></li> |
28 | <li><a href="#write_xy_target_surface_x_y_text">write_xy( $target_surface, $x, $y, $text )</a></li> |
29 | </ul> |
30 | </li> |
31 | <li><a href="#READ_ONLY_ATTRIBUTES">READ-ONLY ATTRIBUTES</a> |
32 | <ul><li><a href="#surface">surface</a></li> |
33 | <li><a href="#w">w</a></li> |
34 | <li><a href="#h">h</a></li> |
35 | </ul> |
36 | </li> |
37 | <li><a href="#ERRORS_AND_DIAGNOSTICS">ERRORS AND DIAGNOSTICS</a></li> |
38 | <li><a href="#BUGS">BUGS</a></li> |
39 | <li><a href="#SUPPORT">SUPPORT</a></li> |
40 | <li><a href="#AUTHORS">AUTHORS</a></li> |
41 | <li><a href="#COPYRIGHT_amp_LICENSE">COPYRIGHT & LICENSE</a></li> |
42 | <li><a href="#SEE_ALSO">SEE ALSO</a> |
43 | </li> |
44 | </ul><hr /> |
45 | <!-- INDEX END --> |
46 | |
47 | <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p> |
48 | <div id="NAME_CONTENT"> |
49 | <p>SDLx::Text - SDL extension for manipulating text</p> |
50 | |
51 | </div> |
52 | <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p> |
53 | <div id="CATEGORY_CONTENT"> |
54 | <p>Extension</p> |
55 | |
56 | </div> |
57 | <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
58 | <div id="SYNOPSIS_CONTENT"> |
59 | <pre> use SDL; |
60 | use SDLx::App; |
61 | use SDLx::Text; |
62 | |
63 | my $app = SDLx::App->new; |
64 | |
65 | my $message = SDLx::Text->new; |
66 | |
67 | $message->write_to( $app, "Hello, World!" ); |
68 | $app->update; |
69 | |
70 | |
71 | |
72 | |
73 | </pre> |
74 | |
75 | </div> |
76 | <h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p> |
77 | <div id="DESCRIPTION_CONTENT"> |
78 | <p>The standard SDL API for handling fonts and rendering text is full of quirks |
79 | and and low-level functions scattered all over the place. This is a sugar |
80 | layer meant to let you easily handle text in your SDL apps.</p> |
81 | |
82 | </div> |
83 | <h1 id="CONSTRUCTION">CONSTRUCTION</h1><p><a href="#TOP" class="toplink">Top</a></p> |
84 | <div id="CONSTRUCTION_CONTENT"> |
85 | |
86 | </div> |
87 | <h2 id="new">new</h2> |
88 | <div id="new_CONTENT"> |
89 | |
90 | </div> |
91 | <h2 id="new_attributes">new ( %attributes )</h2> |
92 | <div id="new_attributes_CONTENT"> |
93 | <p>Instantiates a new SDLx::Text object. All attributes are optional:</p> |
94 | <pre> my $text = SDLx::Text->new( |
95 | font => '/path/to/my/font.ttf', |
96 | color => [255, 255, 255], # "white" |
97 | size => 24, |
98 | x => 0, |
99 | y => 0, |
100 | h_align => 'left', |
101 | text => 'All your base are belong to us.' |
102 | ); |
103 | |
104 | </pre> |
105 | <p>Please check the accessors below for more information on each attribute. |
106 | All values shown above are the <strong>default values</strong>, except for "text", |
107 | which defaults to <code>undef</code>; and "font", which if not provided will load |
108 | the <code>Gentium Basic</code> free font (see "<a href="http://search.cpan.org/perldoc?">http://search.cpan.org/perldoc?</a>" for more |
109 | information).</p> |
110 | |
111 | </div> |
112 | <h1 id="ACCESSORS">ACCESSORS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
113 | <div id="ACCESSORS_CONTENT"> |
114 | <p>All accessors below can be used to get and set their respective attributes. |
115 | For example:</p> |
116 | <pre> my $font_name = $self->font; # gets the font filename |
117 | $self->font( 'somefont.ttf' ); # sets a new font |
118 | |
119 | </pre> |
120 | <p>All accessors return their current value, after being set.</p> |
121 | |
122 | </div> |
123 | <h2 id="x">x</h2> |
124 | <div id="x_CONTENT"> |
125 | <p>Gets/sets the left (x) positioning of the text to be rendered, relative |
126 | to whatever surface you are placing it into.</p> |
127 | |
128 | </div> |
129 | <h2 id="y">y</h2> |
130 | <div id="y_CONTENT"> |
131 | <p>Gets/sets the top (y) positioning of the text to be rendered, relative |
132 | to whatever surface you are placing it into.</p> |
133 | |
134 | </div> |
135 | <h2 id="h_align">h_align</h2> |
136 | <div id="h_align_CONTENT"> |
137 | <p>Gets/sets the horizontal alignment of the text to be rendered relative to |
138 | whatever surface you are placing it into. Available alignments are '<code>left</code>', |
139 | '<code>right</code>' and '<code>center</code>'. Default is '<code>left</code>'.</p> |
140 | |
141 | </div> |
142 | <h2 id="color">color</h2> |
143 | <div id="color_CONTENT"> |
144 | <p>Gets/sets the text color. The color is an array reference in <code>[R, G, B]</code> or <code>[R, G, B, A]</code> format. See <a href="SDL-Color.html">SDL::Color</a> for more information on colors.</p> |
145 | |
146 | </div> |
147 | <h2 id="size">size</h2> |
148 | <div id="size_CONTENT"> |
149 | <p>Gets/sets the font size.</p> |
150 | |
151 | </div> |
152 | <h2 id="font">font</h2> |
153 | <div id="font_CONTENT"> |
154 | <p>Pass it a string containing the path to your desired font to use it. Fonts |
155 | can be in TTF, OTF or FON formats. Generates an exception if the font |
156 | cannot be loaded.</p> |
157 | <p>Returns the <a href="SDL-TTF-Font.html">SDL::TTF::Font</a> object representing the font.</p> |
158 | |
159 | |
160 | |
161 | |
162 | |
163 | </div> |
164 | <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
165 | <div id="METHODS_CONTENT"> |
166 | |
167 | </div> |
168 | <h2 id="text_some_text">text( $some_text )</h2> |
169 | <div id="text_some_text_CONTENT"> |
170 | <p>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.</p> |
171 | <pre> my $obj = SDLx::Text->new->text( "Hello, Dave." ); |
172 | |
173 | </pre> |
174 | <p>Text will always be rendered as utf8, so you can pass any string containing |
175 | regular ASCII or valid utf8 characters.</p> |
176 | |
177 | </div> |
178 | <h2 id="write_to_target_surface">write_to( $target_surface )</h2> |
179 | <div id="write_to_target_surface_CONTENT"> |
180 | |
181 | </div> |
182 | <h2 id="write_to_target_surface_quot_text_to">write_to( $target_surface, "text to write" )</h2> |
183 | <div id="write_to_target_surface_quot_text_to-2"> |
184 | <p>Renders the text onto <code>$target_surface</code> (usually the app itself). The |
185 | text string may be passed as a parameter, otherwise it will use whatever |
186 | is already set (via the <code>new()</code> or <code>text()</code> methods.</p> |
187 | |
188 | </div> |
189 | <h2 id="write_xy_target_surface_x_y">write_xy( $target_surface, $x, $y )</h2> |
190 | <div id="write_xy_target_surface_x_y_CONTENT"> |
191 | |
192 | </div> |
193 | <h2 id="write_xy_target_surface_x_y_text">write_xy( $target_surface, $x, $y, $text )</h2> |
194 | <div id="write_xy_target_surface_x_y_text_CON"> |
195 | <p>Same as <code>write_to()</code>, but will render the text using the given top (y) and |
196 | left (x) coordinates.</p> |
197 | |
198 | |
199 | |
200 | |
201 | |
202 | </div> |
203 | <h1 id="READ_ONLY_ATTRIBUTES">READ-ONLY ATTRIBUTES</h1><p><a href="#TOP" class="toplink">Top</a></p> |
204 | <div id="READ_ONLY_ATTRIBUTES_CONTENT"> |
205 | <p>As you set or update your text, font or size, SDLx::Text updates the surface |
206 | that represents it. You don't usually need to worry about this at all, and |
207 | we strongly recommend you use the <a href="http://search.cpan.org/perldoc?">http://search.cpan.org/perldoc?</a> above to render your text.</p> |
208 | <p>If however you need to know how tall or wide the rendered text will be |
209 | (in pixels), or if you want to retrieve the surface so you can manipulate and |
210 | render it yourself, you can use the following getters:</p> |
211 | |
212 | </div> |
213 | <h2 id="surface">surface</h2> |
214 | <div id="surface_CONTENT"> |
215 | <p>Returns the underlying surface representing the text itself. You probably don't need this, unless you're doing something really funky.</p> |
216 | |
217 | </div> |
218 | <h2 id="w">w</h2> |
219 | <div id="w_CONTENT"> |
220 | <p>Shortcut to see the width of the underlying surface representing the text.</p> |
221 | |
222 | </div> |
223 | <h2 id="h">h</h2> |
224 | <div id="h_CONTENT"> |
225 | <p>Shortcut to see the height of the underlying surface representing the text.</p> |
226 | |
227 | </div> |
228 | <h1 id="ERRORS_AND_DIAGNOSTICS">ERRORS AND DIAGNOSTICS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
229 | <div id="ERRORS_AND_DIAGNOSTICS_CONTENT"> |
230 | <dl> |
231 | <dt>* "SDL_ttf support has not been compiled"</dt> |
232 | <dd> |
233 | <p>In order to render text in SDL you must have enabled SDL_ttf while building <a href="http://search.cpan.org/perldoc?Alien::SDL">Alien::SDL</a>.</p> |
234 | </dd> |
235 | <dt>* "Cannot init TTF: <some error>"</dt> |
236 | <dd> |
237 | <p>In order to load fonts and render text, we need to initialize <a href="SDL-TTF.html">SDL::TTF</a> |
238 | - that is, in case it hasn't been initialized already. The error above will |
239 | appear in the rare event of any problem during initialization.</p> |
240 | </dd> |
241 | <dt>* "Error opening font: <some error>"</dt> |
242 | <dd> |
243 | <p>The font file you set either via <code>font( 'font.ttf' )</code> or during |
244 | construction could not be loaded. The file may not exist in the given path, |
245 | have wrong permissions, be corrupted, or of an unsupported format. Please |
246 | refer the <code><some error></code> message in the message itself for further |
247 | information.</p> |
248 | </dd> |
249 | <dt>* "TTF rendering error: <some error>"</dt> |
250 | <dd> |
251 | <p>When you call <code>text()</code>, it renders the provided string onto an internal |
252 | <a href="SDL-Surface.html">SDL::Surface</a> object. If there was any problem rendering the text, this |
253 | message will appear.</p> |
254 | </dd> |
255 | </dl> |
256 | |
257 | </div> |
258 | <h1 id="BUGS">BUGS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
259 | <div id="BUGS_CONTENT"> |
260 | <p>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.</p> |
261 | |
262 | |
263 | |
264 | |
265 | |
266 | </div> |
267 | <h1 id="SUPPORT">SUPPORT</h1><p><a href="#TOP" class="toplink">Top</a></p> |
268 | <div id="SUPPORT_CONTENT"> |
269 | <p>You can find documentation for this module with the perldoc command.</p> |
270 | <pre> perldoc SDLx::Text |
271 | |
272 | |
273 | |
274 | |
275 | </pre> |
276 | |
277 | </div> |
278 | <h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
279 | <div id="AUTHORS_CONTENT"> |
280 | <p>See <a href="/SDL.html#AUTHORS">/SDL.html#AUTHORS</a>.</p> |
281 | |
282 | |
283 | |
284 | |
285 | |
286 | </div> |
287 | <h1 id="COPYRIGHT_amp_LICENSE">COPYRIGHT & LICENSE</h1><p><a href="#TOP" class="toplink">Top</a></p> |
288 | <div id="COPYRIGHT_amp_LICENSE_CONTENT"> |
289 | <p>This program is free software; you can redistribute it and/or modify it |
290 | under the same terms as Perl itself.</p> |
291 | <p>This module ships with a default font, "<i>Gentium Basic</i>", 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 <code>OFL.txt</code> and <code>OFL-FAQ.txt</code> for further information.</p> |
292 | |
293 | </div> |
294 | <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p> |
295 | <div id="SEE_ALSO_CONTENT"> |
296 | <p><a href="SDL.html">SDL</a>, <a href="SDLx-App.html">SDLx::App</a>, <a href="SDL-TTF.html">SDL::TTF</a> |
297 | </p> |
298 | |
299 | </div> |
300 | </div> |