Merge branch 'master' of git.shadowcat.co.uk:SDL-Site
[sdlgit/SDL-Site.git] / pages / SDL-Pango.html-inc
CommitLineData
c785ed89 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="#CONSTANTS">CONSTANTS</a></li>
9<li><a href="#METHODS">METHODS</a>
10<ul><li><a href="#init">init</a></li>
11<li><a href="#was_init">was_init</a></li>
12<li><a href="#set_default_color">set_default_color</a></li>
13<li><a href="#set_minimum_size">set_minimum_size</a></li>
14<li><a href="#set_text">set_text</a></li>
15<li><a href="#set_markup">set_markup</a></li>
16<li><a href="#get_layout_width">get_layout_width</a></li>
17<li><a href="#get_layout_height">get_layout_height</a></li>
18<li><a href="#set_base_direction">set_base_direction</a></li>
19<li><a href="#set_dpi">set_dpi</a></li>
20<li><a href="#set_language">set_language</a></li>
21<li><a href="#draw">draw</a></li>
22<li><a href="#set_surface_create_args">set_surface_create_args</a></li>
23<li><a href="#create_surface_draw">create_surface_draw</a></li>
24</ul>
25</li>
c7e8d3c6 26<li><a href="#AUTHORS">AUTHORS</a></li>
c785ed89 27<li><a href="#SEE_ALSO">SEE ALSO</a>
28</li>
29</ul><hr />
30<!-- INDEX END -->
31
32<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
33<div id="NAME_CONTENT">
34<p>SDL::Pango - Text rendering engine</p>
35
36</div>
37<h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
38<div id="CATEGORY_CONTENT">
3e29ec77 39<p>Pango</p>
c785ed89 40
41</div>
42<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
43<div id="SYNOPSIS_CONTENT">
44<pre> use SDL;
45 use SDL::Color;
46 use SDL::Surface;
47 use SDL::Overlay;
48 use SDL::Rect;
49 use SDL::Video;
50 use SDL::PixelFormat;
51 use SDL::Pango;
52 use SDL::Pango::Context;
53
54 SDL::Pango::init();
55
f373167e 56 my $context = SDL::Pango::Context-&gt;new;
c785ed89 57 SDL::Pango::set_default_color($context, 0xA7C344FF, 0);
58 SDL::Pango::set_markup($context, 'Hallo &lt;b&gt;W&lt;span foreground=&quot;red&quot;&gt;o&lt;/span&gt;&lt;i&gt;r&lt;/i&gt;&lt;u&gt;l&lt;/u&gt;d&lt;/b&gt;!', -1);
59
60 SDL::init(SDL_INIT_VIDEO);
61
62 my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
63 my $bg = SDL::Video::map_RGB($display-&gt;format, 0x12, 0x22, 0x45);
64 SDL::Video::fill_rect($display, SDL::Rect-&gt;new(0, 0, 640, 480), $bg);
65
66 my $surface = SDL::Pango::create_surface_draw($context);
67 SDL::Video::blit_surface($surface, SDL::Rect-&gt;new(0, 0, 640, 480), $display, SDL::Rect-&gt;new(0, 0, 640, 480));
68
69 SDL::Video::update_rect($display, 0, 0, 0, 0);
70 SDL::delay(2000);
71
72</pre>
73
74</div>
75<h1 id="CONSTANTS">CONSTANTS</h1><p><a href="#TOP" class="toplink">Top</a></p>
76<div id="CONSTANTS_CONTENT">
3549ee6a 77<p>The constants are exported by default. You can avoid this by doing:</p>
78<pre> use SDL::Pango ();
c785ed89 79
80</pre>
3549ee6a 81<p>and access them directly:</p>
c785ed89 82<pre> SDL::Pango::SDLPANGO_DIRECTION_NEUTRAL;
83
84</pre>
a43a516b 85<p>or by choosing the export tags below:</p>
86<p>Export tag: ':align'</p>
87<dl>
88 <dt>SDLPANGO_ALIGN_LEFT</dt>
89 <dd>
90 <p>Left alignment</p>
91 </dd>
92 <dt>SDLPANGO_ALIGN_CENTER</dt>
93 <dd>
94 <p>Centered</p>
95 </dd>
96 <dt>SDLPANGO_ALIGN_RIGHT</dt>
97 <dd>
98 <p>Right alignment</p>
99 </dd>
100</dl>
101<p>Export tag: ':direction'</p>
c785ed89 102<dl>
103 <dt>SDLPANGO_DIRECTION_LTR</dt>
104 <dd>
105 <p>Left to right</p>
106 </dd>
107 <dt>SDLPANGO_DIRECTION_RTL</dt>
108 <dd>
109 <p>Right to left</p>
110 </dd>
111 <dt>SDLPANGO_DIRECTION_WEAK_LTR</dt>
112 <dd>
113 <p>Left to right (weak)</p>
114 </dd>
115 <dt>SDLPANGO_DIRECTION_WEAK_RTL</dt>
116 <dd>
117 <p>Right to left (weak)</p>
118 </dd>
119 <dt>SDLPANGO_DIRECTION_NEUTRAL</dt>
120 <dd>
121 <p>Neutral</p>
122 </dd>
123</dl>
124
125</div>
126<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
127<div id="METHODS_CONTENT">
128
129</div>
130<h2 id="init">init</h2>
131<div id="init_CONTENT">
132<pre> SDL::Pango::init();
133
134</pre>
1dbe1697 135<p>Initialize the Glib and Pango API. This must be called before using other functions in this library, excepting <a href="/SDL-Pango.html#was_init">SDL::Pango::was_init</a>.
3e29ec77 136SDL does not have to be initialized before this call.</p>
137<p>Returns: always <code>0</code>. </p>
c785ed89 138
139</div>
140<h2 id="was_init">was_init</h2>
141<div id="was_init_CONTENT">
142<pre> my $was_init = SDL::Pango::was_init();
143
144</pre>
1dbe1697 145<p>Query the initilization status of the Glib and Pango API. You may, of course, use this before <a href="/SDL-Pango.html#init">SDL::Pango::init</a> to avoid initilizing twice
3e29ec77 146in a row.</p>
147<p>Returns: Non-zero when already initialized. Zero when not initialized.</p>
c785ed89 148
149</div>
150<h2 id="set_default_color">set_default_color</h2>
151<div id="set_default_color_CONTENT">
3e29ec77 152<pre> SDL::Pango::set_default_color($context, $foreground, $background);
153 SDL::Pango::set_default_color($context, $r1, $g1, $b1, $a1, $r2, $g2, $b2, $a2);
c785ed89 154
155</pre>
3e29ec77 156<p>Sets default foreground and background color when rendering text and markup.</p>
157<p>You can call it with either 2 color-parameters (32-bit RRGGBBAA values), or with 4 separate values for foreground and 4 separate values for
158background.</p>
c785ed89 159
160</div>
161<h2 id="set_minimum_size">set_minimum_size</h2>
162<div id="set_minimum_size_CONTENT">
3e29ec77 163<pre> SDL::Pango::set_minimum_size($context, $width, $height);
c785ed89 164
165</pre>
3e29ec77 166<p>Sets the minimum size of the drawing rectangle.</p>
c785ed89 167
168</div>
169<h2 id="set_text">set_text</h2>
170<div id="set_text_CONTENT">
3e29ec77 171<pre> SDL::Pango::set_text($context, $text, $length);
a43a516b 172 SDL::Pango::set_text($context, $text, $length, $alignment);
c785ed89 173
174</pre>
3e29ec77 175<p>Set plain text to context. Text must be utf-8. <code>$length</code> chars will be rendered, pass <code>-1</code> to render the whole text.</p>
a43a516b 176<p><code>$alignment</code> can be:</p>
177<ul>
178 <li>SDLPANGO_ALIGN_LEFT (default) </li>
179 <li>SDLPANGO_ALIGN_CENTER </li>
180 <li>SDLPANGO_ALIGN_RIGHT</li>
181</ul>
182
c785ed89 183
184</div>
185<h2 id="set_markup">set_markup</h2>
186<div id="set_markup_CONTENT">
3e29ec77 187<pre> SDL::Pango::set_markup($context, $text, $length);
c785ed89 188
189</pre>
3e29ec77 190<p>Set markup text to context. Text must be utf-8. <code>$length</code> chars will be rendered, pass <code>-1</code> to render the whole text.</p>
191<p>See <a href="http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html">PangoMarkupFormat</a> for a description about the markup format.</p>
c785ed89 192
193</div>
194<h2 id="get_layout_width">get_layout_width</h2>
195<div id="get_layout_width_CONTENT">
196<pre> my $w = SDL::Pango::get_layout_width($context);
197
198</pre>
3e29ec77 199<p>Returns the width of the resulting surface of the given text/markup for this context.</p>
c785ed89 200
201</div>
202<h2 id="get_layout_height">get_layout_height</h2>
203<div id="get_layout_height_CONTENT">
204<pre> my $h = SDL::Pango::get_layout_height($context);
205
206</pre>
3e29ec77 207<p>Returns the height of the resulting surface of the given text/markup for this context.</p>
c785ed89 208
209</div>
210<h2 id="set_base_direction">set_base_direction</h2>
211<div id="set_base_direction_CONTENT">
3e29ec77 212<pre> SDL::Pango::set_base_direction($context, $direction);
c785ed89 213
214</pre>
3e29ec77 215<p>Sets the direction of the text to either left-to-right or right-to-left.</p>
1dbe1697 216<p>See <a href="http://search.cpan.org/perldoc?">http://search.cpan.org/perldoc?</a>.</p>
c785ed89 217
218</div>
219<h2 id="set_dpi">set_dpi</h2>
220<div id="set_dpi_CONTENT">
3e29ec77 221<pre> SDL::Pango::set_dpi($context, $dpi_x, $dpi_y);
c785ed89 222
223</pre>
3e29ec77 224<p>Sets the DPI (dots per inch) for this context. Default is <code>96</code>.</p>
c785ed89 225
226</div>
227<h2 id="set_language">set_language</h2>
228<div id="set_language_CONTENT">
3e29ec77 229<pre> SDL::Pango::set_language($context, $language);
230
231</pre>
232<p>Sets the language name for this context.</p>
233<p>See <a href="http://www.loc.gov/standards/iso639-2/php/code_list.php">ISO639-2</a>.</p>
234<p>Example:</p>
c785ed89 235<pre> SDL::Pango::set_language($context, &quot;en&quot;);
236
237</pre>
238
239</div>
240<h2 id="draw">draw</h2>
241<div id="draw_CONTENT">
3e29ec77 242<pre> SDL::Pango::draw($context, $display, $x, $y);
c785ed89 243
244</pre>
3e29ec77 245<p>Draws the text or markup to an existing surface at position <code>$x</code>/<code>$y</code>.</p>
c785ed89 246
247</div>
248<h2 id="set_surface_create_args">set_surface_create_args</h2>
249<div id="set_surface_create_args_CONTENT">
3e29ec77 250<pre> SDL::Pango::set_surface_create_args($context, $flags, $bits, $r_mask, $g_mask, $b_mask, $a_mask);
251
252</pre>
1dbe1697 253<p>Sets the argumet that are used when creating a surface via <a href="/SDL-Pango.html#create_surface_draw">SDL::Pango::create_surface_draw</a>.</p>
3e29ec77 254<p>Example:</p>
255<pre> SDL::Pango::set_surface_create_args(
256 $context,
257 SDL_SWSURFACE,
258 32,
259 0xFF000000,
260 0x00FF0000,
261 0x0000FF00,
262 0x000000FF
263 );
c785ed89 264
265</pre>
266
267</div>
268<h2 id="create_surface_draw">create_surface_draw</h2>
269<div id="create_surface_draw_CONTENT">
270<pre> my $surface = SDL::Pango::create_surface_draw($context);
271
272</pre>
1dbe1697 273<p>Creates a new surface and draws the text/markup. You can specify the attributes of the surfaces using <a href="/SDL-Pango.html#set_surface_create_args">SDL::Pango::set_surface_create_args</a>.</p>
c785ed89 274
275</div>
c7e8d3c6 276<h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p>
277<div id="AUTHORS_CONTENT">
1dbe1697 278<p>See <a href="/SDL.html#AUTHORS">/SDL.html#AUTHORS</a>.</p>
c785ed89 279
280</div>
281<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
282<div id="SEE_ALSO_CONTENT">
283<p><a href="SDL-Pango-Context.html">SDL::Pango::Context</a>, <a href="SDL-Video.html">SDL::Video</a>, <a href="SDL-Surface.html">SDL::Surface</a>, <a href="SDL-TTF.html">SDL::TTF</a></p>
284
285</div>
286</div>