/lib/pods/SDL/Pango.pod

  1
  2=pod
  3
  4=head1 NAME
  5
  6SDL::Pango - Text rendering engine
  7
  8=head1 CATEGORY
  9
 10Pango
 11
 12=head1 SYNOPSIS
 13
 14 use SDL;
 15 use SDL::Color;
 16 use SDL::Surface;
 17 use SDL::Overlay;
 18 use SDL::Rect;
 19 use SDL::Video;
 20 use SDL::PixelFormat;
 21 use SDL::Pango;
 22 use SDL::Pango::Context;
 23 
 24 SDL::Pango::init();
 25 
 26 my $context = SDL::Pango::Context->new;
 27 SDL::Pango::set_default_color($context, 0xA7C344FF, 0);
 28 SDL::Pango::set_markup($context, 'Hello <b>W<span foreground="red">o</span><i>r</i><u>l</u>d</b>!', -1);
 29
 30 SDL::init(SDL_INIT_VIDEO);
 31 
 32 my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
 33 my $bg      = SDL::Video::map_RGB($display->format, 0x12, 0x22, 0x45);
 34 SDL::Video::fill_rect($display, SDL::Rect->new(0, 0, 640, 480), $bg);
 35
 36 my $surface = SDL::Pango::create_surface_draw($context);
 37 SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(0, 0, 640, 480));
 38 
 39 SDL::Video::update_rect($display, 0, 0, 0, 0);
 40 SDL::delay(2000);
 41
 42=head1 CONSTANTS
 43
 44The constants are exported by default. You can avoid this by doing:
 45
 46 use SDL::Pango ();
 47
 48and access them directly:
 49
 50 SDL::Pango::SDLPANGO_DIRECTION_NEUTRAL;
 51
 52or by choosing the export tags below:
 53
 54Export tag: ':align'
 55
 56=over 4
 57
 58=item SDLPANGO_ALIGN_LEFT
 59
 60Left alignment
 61
 62=item SDLPANGO_ALIGN_CENTER
 63
 64Centered
 65
 66=item SDLPANGO_ALIGN_RIGHT
 67
 68Right alignment
 69
 70=back
 71
 72Export tag: ':direction'
 73
 74=over 4
 75
 76=item SDLPANGO_DIRECTION_LTR
 77
 78Left to right
 79
 80=item SDLPANGO_DIRECTION_RTL
 81
 82Right to left
 83
 84=item SDLPANGO_DIRECTION_WEAK_LTR
 85
 86Left to right (weak)
 87
 88=item SDLPANGO_DIRECTION_WEAK_RTL
 89
 90Right to left (weak)
 91
 92=item SDLPANGO_DIRECTION_NEUTRAL
 93
 94Neutral
 95
 96=back
 97
 98=head1 METHODS
 99
100=head2 init
101
102 SDL::Pango::init();
103
104Initialize the Glib and Pango API. This must be called before using other functions in this library, excepting L<SDL::Pango::was_init|SDL::Pango/"was_init">. 
105SDL does not have to be initialized before this call.
106
107Returns: always C<0>. 
108
109=head2 was_init
110
111 my $was_init = SDL::Pango::was_init();
112
113Query the initialization status of the Glib and Pango API. You may, of course, use this before L<SDL::Pango::init|SDL::Pango/"init"> to avoid initializing twice 
114in a row.
115
116Returns: Non-zero when already initialized. Zero when not initialized.
117 
118=head2 set_default_color
119
120 SDL::Pango::set_default_color($context, $foreground, $background);
121 SDL::Pango::set_default_color($context, $r1, $g1, $b1, $a1, $r2, $g2, $b2, $a2);
122
123Sets default foreground and background color when rendering text and markup.
124
125You can call it with either 2 color-parameters (32-bit RRGGBBAA values), or with 4 separate values for foreground and 4 separate values for 
126background.
127
128=head2 set_minimum_size
129
130 SDL::Pango::set_minimum_size($context, $width, $height);
131
132Sets the minimum size of the drawing rectangle.
133
134=head2 set_text
135
136 SDL::Pango::set_text($context, $text, $length);
137 SDL::Pango::set_text($context, $text, $length, $alignment);
138
139Set plain text to context. Text must be utf-8. C<$length> chars will be rendered, pass C<-1> to render the whole text.
140
141C<$alignment> can be:
142
143=over 4
144
145=item *
146
147SDLPANGO_ALIGN_LEFT (default)
148
149=item *
150
151SDLPANGO_ALIGN_CENTER
152
153=item *
154
155SDLPANGO_ALIGN_RIGHT
156
157=back
158
159=head2 set_markup
160
161 SDL::Pango::set_markup($context, $text, $length);
162
163Set markup text to context. Text must be utf-8. C<$length> chars will be rendered, pass C<-1> to render the whole text.
164
165See L<PangoMarkupFormat|http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html> for a description about the markup format.
166
167=head2 get_layout_width
168
169 my $w = SDL::Pango::get_layout_width($context);
170
171Returns the width of the resulting surface of the given text/markup for this context.
172
173=head2 get_layout_height
174
175 my $h = SDL::Pango::get_layout_height($context);
176
177Returns the height of the resulting surface of the given text/markup for this context.
178
179=head2 set_base_direction
180
181 SDL::Pango::set_base_direction($context, $direction);
182
183Sets the direction of the text to either left-to-right or right-to-left.
184
185See L</CONSTANTS>.
186
187=head2 set_dpi
188
189 SDL::Pango::set_dpi($context, $dpi_x, $dpi_y);
190
191Sets the DPI (dots per inch) for this context. Default is C<96>.
192
193=head2 set_language
194
195 SDL::Pango::set_language($context, $language);
196
197Sets the language name for this context.
198
199See L<ISO639-2|http://www.loc.gov/standards/iso639-2/php/code_list.php>.
200
201Example:
202
203 SDL::Pango::set_language($context, "en");
204
205=head2 draw
206
207 SDL::Pango::draw($context, $display, $x, $y);
208
209Draws the text or markup to an existing surface at position C<$x>/C<$y>.
210
211=head2 set_surface_create_args
212
213 SDL::Pango::set_surface_create_args($context, $flags, $bits, $r_mask, $g_mask, $b_mask, $a_mask);
214
215Sets the argument that are used when creating a surface via L<SDL::Pango::create_surface_draw|SDL::Pango/"create_surface_draw">.
216
217Example:
218
219 SDL::Pango::set_surface_create_args(
220     $context, 
221     SDL_SWSURFACE, 
222     32, 
223     0xFF000000, 
224     0x00FF0000, 
225     0x0000FF00, 
226     0x000000FF
227 );
228
229=head2 create_surface_draw
230
231 my $surface = SDL::Pango::create_surface_draw($context);
232
233Creates a new surface and draws the text/markup. You can specify the attributes of the surfaces using L<SDL::Pango::set_surface_create_args|SDL::Pango/"set_surface_create_args">.
234
235=head1 AUTHORS
236
237See L<SDL/AUTHORS>.
238
239=head1 SEE ALSO
240
241L<SDL::Pango::Context>, L<SDL::Video>, L<SDL::Surface>, L<SDL::TTF>
242
243=cut