Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/gtk-doc/html/cairo/cairo-text.html @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>text: Cairo: A Vector Graphics Library</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="index.html" title="Cairo: A Vector Graphics Library">
8 <link rel="up" href="cairo-drawing.html" title="Drawing">
9 <link rel="prev" href="cairo-Transformations.html" title="Transformations">
10 <link rel="next" href="cairo-Raster-Sources.html" title="Raster Sources">
11 <meta name="generator" content="GTK-Doc V1.27 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
13 </head>
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
16 <td width="100%" align="left" class="shortcuts">
17 <a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span> 
18 <a href="#cairo-text.description" class="shortcut">Description</a></span>
19 </td>
20 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
21 <td><a accesskey="u" href="cairo-drawing.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
22 <td><a accesskey="p" href="cairo-Transformations.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
23 <td><a accesskey="n" href="cairo-Raster-Sources.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
24 </tr></table>
25 <div class="refentry">
26 <a name="cairo-text"></a><div class="titlepage"></div>
27 <div class="refnamediv"><table width="100%"><tr>
28 <td valign="top">
29 <h2><span class="refentrytitle"><a name="cairo-text.top_of_page"></a>text</span></h2>
30 <p>text — Rendering text and glyphs</p>
31 </td>
32 <td class="gallery_image" valign="top" align="right"></td>
33 </tr></table></div>
34 <div class="refsect1">
35 <a name="cairo-text.functions"></a><h2>Functions</h2>
36 <div class="informaltable"><table class="informaltable" width="100%" border="0">
37 <colgroup>
38 <col width="150px" class="functions_return">
39 <col class="functions_name">
40 </colgroup>
41 <tbody>
42 <tr>
43 <td class="function_type">
44 <span class="returnvalue">void</span>
45 </td>
46 <td class="function_name">
47 <a class="link" href="cairo-text.html#cairo-select-font-face" title="cairo_select_font_face ()">cairo_select_font_face</a> <span class="c_punctuation">()</span>
48 </td>
49 </tr>
50 <tr>
51 <td class="function_type">
52 <span class="returnvalue">void</span>
53 </td>
54 <td class="function_name">
55 <a class="link" href="cairo-text.html#cairo-set-font-size" title="cairo_set_font_size ()">cairo_set_font_size</a> <span class="c_punctuation">()</span>
56 </td>
57 </tr>
58 <tr>
59 <td class="function_type">
60 <span class="returnvalue">void</span>
61 </td>
62 <td class="function_name">
63 <a class="link" href="cairo-text.html#cairo-set-font-matrix" title="cairo_set_font_matrix ()">cairo_set_font_matrix</a> <span class="c_punctuation">()</span>
64 </td>
65 </tr>
66 <tr>
67 <td class="function_type">
68 <span class="returnvalue">void</span>
69 </td>
70 <td class="function_name">
71 <a class="link" href="cairo-text.html#cairo-get-font-matrix" title="cairo_get_font_matrix ()">cairo_get_font_matrix</a> <span class="c_punctuation">()</span>
72 </td>
73 </tr>
74 <tr>
75 <td class="function_type">
76 <span class="returnvalue">void</span>
77 </td>
78 <td class="function_name">
79 <a class="link" href="cairo-text.html#cairo-set-font-options" title="cairo_set_font_options ()">cairo_set_font_options</a> <span class="c_punctuation">()</span>
80 </td>
81 </tr>
82 <tr>
83 <td class="function_type">
84 <span class="returnvalue">void</span>
85 </td>
86 <td class="function_name">
87 <a class="link" href="cairo-text.html#cairo-get-font-options" title="cairo_get_font_options ()">cairo_get_font_options</a> <span class="c_punctuation">()</span>
88 </td>
89 </tr>
90 <tr>
91 <td class="function_type">
92 <span class="returnvalue">void</span>
93 </td>
94 <td class="function_name">
95 <a class="link" href="cairo-text.html#cairo-set-font-face" title="cairo_set_font_face ()">cairo_set_font_face</a> <span class="c_punctuation">()</span>
96 </td>
97 </tr>
98 <tr>
99 <td class="function_type">
100 <a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="returnvalue">cairo_font_face_t</span></a> *
101 </td>
102 <td class="function_name">
103 <a class="link" href="cairo-text.html#cairo-get-font-face" title="cairo_get_font_face ()">cairo_get_font_face</a> <span class="c_punctuation">()</span>
104 </td>
105 </tr>
106 <tr>
107 <td class="function_type">
108 <span class="returnvalue">void</span>
109 </td>
110 <td class="function_name">
111 <a class="link" href="cairo-text.html#cairo-set-scaled-font" title="cairo_set_scaled_font ()">cairo_set_scaled_font</a> <span class="c_punctuation">()</span>
112 </td>
113 </tr>
114 <tr>
115 <td class="function_type">
116 <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-t" title="cairo_scaled_font_t"><span class="returnvalue">cairo_scaled_font_t</span></a> *
117 </td>
118 <td class="function_name">
119 <a class="link" href="cairo-text.html#cairo-get-scaled-font" title="cairo_get_scaled_font ()">cairo_get_scaled_font</a> <span class="c_punctuation">()</span>
120 </td>
121 </tr>
122 <tr>
123 <td class="function_type">
124 <span class="returnvalue">void</span>
125 </td>
126 <td class="function_name">
127 <a class="link" href="cairo-text.html#cairo-show-text" title="cairo_show_text ()">cairo_show_text</a> <span class="c_punctuation">()</span>
128 </td>
129 </tr>
130 <tr>
131 <td class="function_type">
132 <span class="returnvalue">void</span>
133 </td>
134 <td class="function_name">
135 <a class="link" href="cairo-text.html#cairo-show-glyphs" title="cairo_show_glyphs ()">cairo_show_glyphs</a> <span class="c_punctuation">()</span>
136 </td>
137 </tr>
138 <tr>
139 <td class="function_type">
140 <span class="returnvalue">void</span>
141 </td>
142 <td class="function_name">
143 <a class="link" href="cairo-text.html#cairo-show-text-glyphs" title="cairo_show_text_glyphs ()">cairo_show_text_glyphs</a> <span class="c_punctuation">()</span>
144 </td>
145 </tr>
146 <tr>
147 <td class="function_type">
148 <span class="returnvalue">void</span>
149 </td>
150 <td class="function_name">
151 <a class="link" href="cairo-text.html#cairo-font-extents" title="cairo_font_extents ()">cairo_font_extents</a> <span class="c_punctuation">()</span>
152 </td>
153 </tr>
154 <tr>
155 <td class="function_type">
156 <span class="returnvalue">void</span>
157 </td>
158 <td class="function_name">
159 <a class="link" href="cairo-text.html#cairo-text-extents" title="cairo_text_extents ()">cairo_text_extents</a> <span class="c_punctuation">()</span>
160 </td>
161 </tr>
162 <tr>
163 <td class="function_type">
164 <span class="returnvalue">void</span>
165 </td>
166 <td class="function_name">
167 <a class="link" href="cairo-text.html#cairo-glyph-extents" title="cairo_glyph_extents ()">cairo_glyph_extents</a> <span class="c_punctuation">()</span>
168 </td>
169 </tr>
170 <tr>
171 <td class="function_type">
172 <a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="returnvalue">cairo_font_face_t</span></a> *
173 </td>
174 <td class="function_name">
175 <a class="link" href="cairo-text.html#cairo-toy-font-face-create" title="cairo_toy_font_face_create ()">cairo_toy_font_face_create</a> <span class="c_punctuation">()</span>
176 </td>
177 </tr>
178 <tr>
179 <td class="function_type">const <span class="returnvalue">char</span> *
180 </td>
181 <td class="function_name">
182 <a class="link" href="cairo-text.html#cairo-toy-font-face-get-family" title="cairo_toy_font_face_get_family ()">cairo_toy_font_face_get_family</a> <span class="c_punctuation">()</span>
183 </td>
184 </tr>
185 <tr>
186 <td class="function_type">
187 <a class="link" href="cairo-text.html#cairo-font-slant-t" title="enum cairo_font_slant_t"><span class="returnvalue">cairo_font_slant_t</span></a>
188 </td>
189 <td class="function_name">
190 <a class="link" href="cairo-text.html#cairo-toy-font-face-get-slant" title="cairo_toy_font_face_get_slant ()">cairo_toy_font_face_get_slant</a> <span class="c_punctuation">()</span>
191 </td>
192 </tr>
193 <tr>
194 <td class="function_type">
195 <a class="link" href="cairo-text.html#cairo-font-weight-t" title="enum cairo_font_weight_t"><span class="returnvalue">cairo_font_weight_t</span></a>
196 </td>
197 <td class="function_name">
198 <a class="link" href="cairo-text.html#cairo-toy-font-face-get-weight" title="cairo_toy_font_face_get_weight ()">cairo_toy_font_face_get_weight</a> <span class="c_punctuation">()</span>
199 </td>
200 </tr>
201 <tr>
202 <td class="function_type">
203 <a class="link" href="cairo-text.html#cairo-glyph-t" title="cairo_glyph_t"><span class="returnvalue">cairo_glyph_t</span></a> *
204 </td>
205 <td class="function_name">
206 <a class="link" href="cairo-text.html#cairo-glyph-allocate" title="cairo_glyph_allocate ()">cairo_glyph_allocate</a> <span class="c_punctuation">()</span>
207 </td>
208 </tr>
209 <tr>
210 <td class="function_type">
211 <span class="returnvalue">void</span>
212 </td>
213 <td class="function_name">
214 <a class="link" href="cairo-text.html#cairo-glyph-free" title="cairo_glyph_free ()">cairo_glyph_free</a> <span class="c_punctuation">()</span>
215 </td>
216 </tr>
217 <tr>
218 <td class="function_type">
219 <a class="link" href="cairo-text.html#cairo-text-cluster-t" title="cairo_text_cluster_t"><span class="returnvalue">cairo_text_cluster_t</span></a> *
220 </td>
221 <td class="function_name">
222 <a class="link" href="cairo-text.html#cairo-text-cluster-allocate" title="cairo_text_cluster_allocate ()">cairo_text_cluster_allocate</a> <span class="c_punctuation">()</span>
223 </td>
224 </tr>
225 <tr>
226 <td class="function_type">
227 <span class="returnvalue">void</span>
228 </td>
229 <td class="function_name">
230 <a class="link" href="cairo-text.html#cairo-text-cluster-free" title="cairo_text_cluster_free ()">cairo_text_cluster_free</a> <span class="c_punctuation">()</span>
231 </td>
232 </tr>
233 </tbody>
234 </table></div>
235 </div>
236 <div class="refsect1">
237 <a name="cairo-text.other"></a><h2>Types and Values</h2>
238 <div class="informaltable"><table class="informaltable" width="100%" border="0">
239 <colgroup>
240 <col width="150px" class="name">
241 <col class="description">
242 </colgroup>
243 <tbody>
244 <tr>
245 <td class="datatype_keyword"> </td>
246 <td class="function_name"><a class="link" href="cairo-text.html#cairo-glyph-t" title="cairo_glyph_t">cairo_glyph_t</a></td>
247 </tr>
248 <tr>
249 <td class="datatype_keyword">enum</td>
250 <td class="function_name"><a class="link" href="cairo-text.html#cairo-font-slant-t" title="enum cairo_font_slant_t">cairo_font_slant_t</a></td>
251 </tr>
252 <tr>
253 <td class="datatype_keyword">enum</td>
254 <td class="function_name"><a class="link" href="cairo-text.html#cairo-font-weight-t" title="enum cairo_font_weight_t">cairo_font_weight_t</a></td>
255 </tr>
256 <tr>
257 <td class="datatype_keyword"> </td>
258 <td class="function_name"><a class="link" href="cairo-text.html#cairo-text-cluster-t" title="cairo_text_cluster_t">cairo_text_cluster_t</a></td>
259 </tr>
260 <tr>
261 <td class="datatype_keyword">enum</td>
262 <td class="function_name"><a class="link" href="cairo-text.html#cairo-text-cluster-flags-t" title="enum cairo_text_cluster_flags_t">cairo_text_cluster_flags_t</a></td>
263 </tr>
264 </tbody>
265 </table></div>
266 </div>
267 <div class="refsect1">
268 <a name="cairo-text.description"></a><h2>Description</h2>
269 <p>The functions with <span class="emphasis"><em>text</em></span> in their name form cairo's
270 <em class="firstterm">toy</em> text API. The toy API takes UTF-8 encoded
271 text and is limited in its functionality to rendering simple
272 left-to-right text with no advanced features. That means for example
273 that most complex scripts like Hebrew, Arabic, and Indic scripts are
274 out of question. No kerning or correct positioning of diacritical marks
275 either. The font selection is pretty limited too and doesn't handle the
276 case that the selected font does not cover the characters in the text.
277 This set of functions are really that, a toy text API, for testing and
278 demonstration purposes. Any serious application should avoid them.</p>
279 <p>The functions with <span class="emphasis"><em>glyphs</em></span> in their name form cairo's
280 <em class="firstterm">low-level</em> text API. The low-level API relies on
281 the user to convert text to a set of glyph indexes and positions. This
282 is a very hard problem and is best handled by external libraries, like
283 the pangocairo that is part of the Pango text layout and rendering library.
284 Pango is available from <a class="ulink" href="http://www.pango.org/" target="_top">http://www.pango.org/</a>.</p>
285 </div>
286 <div class="refsect1">
287 <a name="cairo-text.functions_details"></a><h2>Functions</h2>
288 <div class="refsect2">
289 <a name="cairo-select-font-face"></a><h3>cairo_select_font_face ()</h3>
290 <pre class="programlisting"><span class="returnvalue">void</span>
291 cairo_select_font_face (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
292 <em class="parameter"><code>const <span class="type">char</span> *family</code></em>,
293 <em class="parameter"><code><a class="link" href="cairo-text.html#cairo-font-slant-t" title="enum cairo_font_slant_t"><span class="type">cairo_font_slant_t</span></a> slant</code></em>,
294 <em class="parameter"><code><a class="link" href="cairo-text.html#cairo-font-weight-t" title="enum cairo_font_weight_t"><span class="type">cairo_font_weight_t</span></a> weight</code></em>);</pre>
295 <p>Note: The <a class="link" href="cairo-text.html#cairo-select-font-face" title="cairo_select_font_face ()"><code class="function">cairo_select_font_face()</code></a> function call is part of what
296 the cairo designers call the "toy" text API. It is convenient for
297 short demos and simple programs, but it is not expected to be
298 adequate for serious text-using applications.</p>
299 <p>Selects a family and style of font from a simplified description as
300 a family name, slant and weight. Cairo provides no operation to
301 list available family names on the system (this is a "toy",
302 remember), but the standard CSS2 generic family names, ("serif",
303 "sans-serif", "cursive", "fantasy", "monospace"), are likely to
304 work as expected.</p>
305 <p>If <em class="parameter"><code>family</code></em>
306 starts with the string "<em class="parameter"><code>cairo</code></em>
307 :", or if no native font
308 backends are compiled in, cairo will use an internal font family.
309 The internal font family recognizes many modifiers in the <em class="parameter"><code>family</code></em>
310
311 string, most notably, it recognizes the string "monospace". That is,
312 the family name "<em class="parameter"><code>cairo</code></em>
313 :monospace" will use the monospace version of
314 the internal font family.</p>
315 <p>For "real" font selection, see the font-backend-specific
316 font_face_create functions for the font backend you are using. (For
317 example, if you are using the freetype-based cairo-ft font backend,
318 see <a class="link" href="cairo-FreeType-Fonts.html#cairo-ft-font-face-create-for-ft-face" title="cairo_ft_font_face_create_for_ft_face ()"><code class="function">cairo_ft_font_face_create_for_ft_face()</code></a> or
319 <a class="link" href="cairo-FreeType-Fonts.html#cairo-ft-font-face-create-for-pattern" title="cairo_ft_font_face_create_for_pattern ()"><code class="function">cairo_ft_font_face_create_for_pattern()</code></a>.) The resulting font face
320 could then be used with <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-create" title="cairo_scaled_font_create ()"><code class="function">cairo_scaled_font_create()</code></a> and
321 <a class="link" href="cairo-text.html#cairo-set-scaled-font" title="cairo_set_scaled_font ()"><code class="function">cairo_set_scaled_font()</code></a>.</p>
322 <p>Similarly, when using the "real" font support, you can call
323 directly into the underlying font system, (such as fontconfig or
324 freetype), for operations such as listing available fonts, etc.</p>
325 <p>It is expected that most applications will need to use a more
326 comprehensive font handling and text layout library, (for example,
327 pango), in conjunction with cairo.</p>
328 <p>If text is drawn without a call to <a class="link" href="cairo-text.html#cairo-select-font-face" title="cairo_select_font_face ()"><code class="function">cairo_select_font_face()</code></a>, (nor
329 <a class="link" href="cairo-text.html#cairo-set-font-face" title="cairo_set_font_face ()"><code class="function">cairo_set_font_face()</code></a> nor <a class="link" href="cairo-text.html#cairo-set-scaled-font" title="cairo_set_scaled_font ()"><code class="function">cairo_set_scaled_font()</code></a>), the default
330 family is platform-specific, but is essentially "sans-serif".
331 Default slant is <a class="link" href="cairo-text.html#CAIRO-FONT-SLANT-NORMAL:CAPS"><code class="literal">CAIRO_FONT_SLANT_NORMAL</code></a>, and default weight is
332 <a class="link" href="cairo-text.html#CAIRO-FONT-WEIGHT-NORMAL:CAPS"><code class="literal">CAIRO_FONT_WEIGHT_NORMAL</code></a>.</p>
333 <p>This function is equivalent to a call to <a class="link" href="cairo-text.html#cairo-toy-font-face-create" title="cairo_toy_font_face_create ()"><code class="function">cairo_toy_font_face_create()</code></a>
334 followed by <a class="link" href="cairo-text.html#cairo-set-font-face" title="cairo_set_font_face ()"><code class="function">cairo_set_font_face()</code></a>.</p>
335 <div class="refsect3">
336 <a name="cairo-select-font-face.parameters"></a><h4>Parameters</h4>
337 <div class="informaltable"><table class="informaltable" width="100%" border="0">
338 <colgroup>
339 <col width="150px" class="parameters_name">
340 <col class="parameters_description">
341 <col width="200px" class="parameters_annotations">
342 </colgroup>
343 <tbody>
344 <tr>
345 <td class="parameter_name"><p>cr</p></td>
346 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
347 <td class="parameter_annotations"> </td>
348 </tr>
349 <tr>
350 <td class="parameter_name"><p>family</p></td>
351 <td class="parameter_description"><p>a font family name, encoded in UTF-8</p></td>
352 <td class="parameter_annotations"> </td>
353 </tr>
354 <tr>
355 <td class="parameter_name"><p>slant</p></td>
356 <td class="parameter_description"><p>the slant for the font</p></td>
357 <td class="parameter_annotations"> </td>
358 </tr>
359 <tr>
360 <td class="parameter_name"><p>weight</p></td>
361 <td class="parameter_description"><p>the weight for the font</p></td>
362 <td class="parameter_annotations"> </td>
363 </tr>
364 </tbody>
365 </table></div>
366 </div>
367 <p class="since">Since: 1.0</p>
368 </div>
369 <hr>
370 <div class="refsect2">
371 <a name="cairo-set-font-size"></a><h3>cairo_set_font_size ()</h3>
372 <pre class="programlisting"><span class="returnvalue">void</span>
373 cairo_set_font_size (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
374 <em class="parameter"><code><span class="type">double</span> size</code></em>);</pre>
375 <p>Sets the current font matrix to a scale by a factor of <em class="parameter"><code>size</code></em>
376 , replacing
377 any font matrix previously set with <a class="link" href="cairo-text.html#cairo-set-font-size" title="cairo_set_font_size ()"><code class="function">cairo_set_font_size()</code></a> or
378 <a class="link" href="cairo-text.html#cairo-set-font-matrix" title="cairo_set_font_matrix ()"><code class="function">cairo_set_font_matrix()</code></a>. This results in a font size of <em class="parameter"><code>size</code></em>
379 user space
380 units. (More precisely, this matrix will result in the font's
381 em-square being a <em class="parameter"><code>size</code></em>
382 by <em class="parameter"><code>size</code></em>
383 square in user space.)</p>
384 <p>If text is drawn without a call to <a class="link" href="cairo-text.html#cairo-set-font-size" title="cairo_set_font_size ()"><code class="function">cairo_set_font_size()</code></a>, (nor
385 <a class="link" href="cairo-text.html#cairo-set-font-matrix" title="cairo_set_font_matrix ()"><code class="function">cairo_set_font_matrix()</code></a> nor <a class="link" href="cairo-text.html#cairo-set-scaled-font" title="cairo_set_scaled_font ()"><code class="function">cairo_set_scaled_font()</code></a>), the default
386 font size is 10.0.</p>
387 <div class="refsect3">
388 <a name="cairo-set-font-size.parameters"></a><h4>Parameters</h4>
389 <div class="informaltable"><table class="informaltable" width="100%" border="0">
390 <colgroup>
391 <col width="150px" class="parameters_name">
392 <col class="parameters_description">
393 <col width="200px" class="parameters_annotations">
394 </colgroup>
395 <tbody>
396 <tr>
397 <td class="parameter_name"><p>cr</p></td>
398 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
399 <td class="parameter_annotations"> </td>
400 </tr>
401 <tr>
402 <td class="parameter_name"><p>size</p></td>
403 <td class="parameter_description"><p>the new font size, in user space units</p></td>
404 <td class="parameter_annotations"> </td>
405 </tr>
406 </tbody>
407 </table></div>
408 </div>
409 <p class="since">Since: 1.0</p>
410 </div>
411 <hr>
412 <div class="refsect2">
413 <a name="cairo-set-font-matrix"></a><h3>cairo_set_font_matrix ()</h3>
414 <pre class="programlisting"><span class="returnvalue">void</span>
415 cairo_set_font_matrix (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
416 <em class="parameter"><code>const <a class="link" href="cairo-cairo-matrix-t.html#cairo-matrix-t" title="cairo_matrix_t"><span class="type">cairo_matrix_t</span></a> *matrix</code></em>);</pre>
417 <p>Sets the current font matrix to <em class="parameter"><code>matrix</code></em>
418 . The font matrix gives a
419 transformation from the design space of the font (in this space,
420 the em-square is 1 unit by 1 unit) to user space. Normally, a
421 simple scale is used (see <a class="link" href="cairo-text.html#cairo-set-font-size" title="cairo_set_font_size ()"><code class="function">cairo_set_font_size()</code></a>), but a more
422 complex font matrix can be used to shear the font
423 or stretch it unequally along the two axes</p>
424 <div class="refsect3">
425 <a name="cairo-set-font-matrix.parameters"></a><h4>Parameters</h4>
426 <div class="informaltable"><table class="informaltable" width="100%" border="0">
427 <colgroup>
428 <col width="150px" class="parameters_name">
429 <col class="parameters_description">
430 <col width="200px" class="parameters_annotations">
431 </colgroup>
432 <tbody>
433 <tr>
434 <td class="parameter_name"><p>cr</p></td>
435 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
436 <td class="parameter_annotations"> </td>
437 </tr>
438 <tr>
439 <td class="parameter_name"><p>matrix</p></td>
440 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-matrix-t.html#cairo-matrix-t" title="cairo_matrix_t"><span class="type">cairo_matrix_t</span></a> describing a transform to be applied to
441 the current font.</p></td>
442 <td class="parameter_annotations"> </td>
443 </tr>
444 </tbody>
445 </table></div>
446 </div>
447 <p class="since">Since: 1.0</p>
448 </div>
449 <hr>
450 <div class="refsect2">
451 <a name="cairo-get-font-matrix"></a><h3>cairo_get_font_matrix ()</h3>
452 <pre class="programlisting"><span class="returnvalue">void</span>
453 cairo_get_font_matrix (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
454 <em class="parameter"><code><a class="link" href="cairo-cairo-matrix-t.html#cairo-matrix-t" title="cairo_matrix_t"><span class="type">cairo_matrix_t</span></a> *matrix</code></em>);</pre>
455 <p>Stores the current font matrix into <em class="parameter"><code>matrix</code></em>
456 . See
457 <a class="link" href="cairo-text.html#cairo-set-font-matrix" title="cairo_set_font_matrix ()"><code class="function">cairo_set_font_matrix()</code></a>.</p>
458 <div class="refsect3">
459 <a name="cairo-get-font-matrix.parameters"></a><h4>Parameters</h4>
460 <div class="informaltable"><table class="informaltable" width="100%" border="0">
461 <colgroup>
462 <col width="150px" class="parameters_name">
463 <col class="parameters_description">
464 <col width="200px" class="parameters_annotations">
465 </colgroup>
466 <tbody>
467 <tr>
468 <td class="parameter_name"><p>cr</p></td>
469 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
470 <td class="parameter_annotations"> </td>
471 </tr>
472 <tr>
473 <td class="parameter_name"><p>matrix</p></td>
474 <td class="parameter_description"><p>return value for the matrix</p></td>
475 <td class="parameter_annotations"> </td>
476 </tr>
477 </tbody>
478 </table></div>
479 </div>
480 <p class="since">Since: 1.0</p>
481 </div>
482 <hr>
483 <div class="refsect2">
484 <a name="cairo-set-font-options"></a><h3>cairo_set_font_options ()</h3>
485 <pre class="programlisting"><span class="returnvalue">void</span>
486 cairo_set_font_options (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
487 <em class="parameter"><code>const <a class="link" href="cairo-cairo-font-options-t.html#cairo-font-options-t" title="cairo_font_options_t"><span class="type">cairo_font_options_t</span></a> *options</code></em>);</pre>
488 <p>Sets a set of custom font rendering options for the <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a>.
489 Rendering options are derived by merging these options with the
490 options derived from underlying surface; if the value in <em class="parameter"><code>options</code></em>
491
492 has a default value (like <a class="link" href="cairo-cairo-t.html#CAIRO-ANTIALIAS-DEFAULT:CAPS"><code class="literal">CAIRO_ANTIALIAS_DEFAULT</code></a>), then the value
493 from the surface is used.</p>
494 <div class="refsect3">
495 <a name="cairo-set-font-options.parameters"></a><h4>Parameters</h4>
496 <div class="informaltable"><table class="informaltable" width="100%" border="0">
497 <colgroup>
498 <col width="150px" class="parameters_name">
499 <col class="parameters_description">
500 <col width="200px" class="parameters_annotations">
501 </colgroup>
502 <tbody>
503 <tr>
504 <td class="parameter_name"><p>cr</p></td>
505 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
506 <td class="parameter_annotations"> </td>
507 </tr>
508 <tr>
509 <td class="parameter_name"><p>options</p></td>
510 <td class="parameter_description"><p>font options to use</p></td>
511 <td class="parameter_annotations"> </td>
512 </tr>
513 </tbody>
514 </table></div>
515 </div>
516 <p class="since">Since: 1.0</p>
517 </div>
518 <hr>
519 <div class="refsect2">
520 <a name="cairo-get-font-options"></a><h3>cairo_get_font_options ()</h3>
521 <pre class="programlisting"><span class="returnvalue">void</span>
522 cairo_get_font_options (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
523 <em class="parameter"><code><a class="link" href="cairo-cairo-font-options-t.html#cairo-font-options-t" title="cairo_font_options_t"><span class="type">cairo_font_options_t</span></a> *options</code></em>);</pre>
524 <p>Retrieves font rendering options set via <a class="link" href="cairo-text.html#cairo-set-font-options" title="cairo_set_font_options ()"><span class="type">cairo_set_font_options</span></a>.
525 Note that the returned options do not include any options derived
526 from the underlying surface; they are literally the options
527 passed to <a class="link" href="cairo-text.html#cairo-set-font-options" title="cairo_set_font_options ()"><code class="function">cairo_set_font_options()</code></a>.</p>
528 <div class="refsect3">
529 <a name="cairo-get-font-options.parameters"></a><h4>Parameters</h4>
530 <div class="informaltable"><table class="informaltable" width="100%" border="0">
531 <colgroup>
532 <col width="150px" class="parameters_name">
533 <col class="parameters_description">
534 <col width="200px" class="parameters_annotations">
535 </colgroup>
536 <tbody>
537 <tr>
538 <td class="parameter_name"><p>cr</p></td>
539 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
540 <td class="parameter_annotations"> </td>
541 </tr>
542 <tr>
543 <td class="parameter_name"><p>options</p></td>
544 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-font-options-t.html#cairo-font-options-t" title="cairo_font_options_t"><span class="type">cairo_font_options_t</span></a> object into which to store
545 the retrieved options. All existing values are overwritten</p></td>
546 <td class="parameter_annotations"> </td>
547 </tr>
548 </tbody>
549 </table></div>
550 </div>
551 <p class="since">Since: 1.0</p>
552 </div>
553 <hr>
554 <div class="refsect2">
555 <a name="cairo-set-font-face"></a><h3>cairo_set_font_face ()</h3>
556 <pre class="programlisting"><span class="returnvalue">void</span>
557 cairo_set_font_face (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
558 <em class="parameter"><code><a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="type">cairo_font_face_t</span></a> *font_face</code></em>);</pre>
559 <p>Replaces the current <a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="type">cairo_font_face_t</span></a> object in the <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> with
560 <em class="parameter"><code>font_face</code></em>
561 . The replaced font face in the <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> will be
562 destroyed if there are no other references to it.</p>
563 <div class="refsect3">
564 <a name="cairo-set-font-face.parameters"></a><h4>Parameters</h4>
565 <div class="informaltable"><table class="informaltable" width="100%" border="0">
566 <colgroup>
567 <col width="150px" class="parameters_name">
568 <col class="parameters_description">
569 <col width="200px" class="parameters_annotations">
570 </colgroup>
571 <tbody>
572 <tr>
573 <td class="parameter_name"><p>cr</p></td>
574 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
575 <td class="parameter_annotations"> </td>
576 </tr>
577 <tr>
578 <td class="parameter_name"><p>font_face</p></td>
579 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="type">cairo_font_face_t</span></a>, or <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to restore to the default font</p></td>
580 <td class="parameter_annotations"> </td>
581 </tr>
582 </tbody>
583 </table></div>
584 </div>
585 <p class="since">Since: 1.0</p>
586 </div>
587 <hr>
588 <div class="refsect2">
589 <a name="cairo-get-font-face"></a><h3>cairo_get_font_face ()</h3>
590 <pre class="programlisting"><a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="returnvalue">cairo_font_face_t</span></a> *
591 cairo_get_font_face (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>);</pre>
592 <p>Gets the current font face for a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a>.</p>
593 <div class="refsect3">
594 <a name="cairo-get-font-face.parameters"></a><h4>Parameters</h4>
595 <div class="informaltable"><table class="informaltable" width="100%" border="0">
596 <colgroup>
597 <col width="150px" class="parameters_name">
598 <col class="parameters_description">
599 <col width="200px" class="parameters_annotations">
600 </colgroup>
601 <tbody><tr>
602 <td class="parameter_name"><p>cr</p></td>
603 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
604 <td class="parameter_annotations"> </td>
605 </tr></tbody>
606 </table></div>
607 </div>
608 <div class="refsect3">
609 <a name="cairo-get-font-face.returns"></a><h4>Returns</h4>
610 <p> the current font face. This object is owned by
611 cairo. To keep a reference to it, you must call
612 <a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-reference" title="cairo_font_face_reference ()"><code class="function">cairo_font_face_reference()</code></a>.</p>
613 <p>This function never returns <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. If memory cannot be allocated, a
614 special "nil" <a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="type">cairo_font_face_t</span></a> object will be returned on which
615 <a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-status" title="cairo_font_face_status ()"><code class="function">cairo_font_face_status()</code></a> returns <a class="link" href="cairo-Error-handling.html#CAIRO-STATUS-NO-MEMORY:CAPS"><code class="literal">CAIRO_STATUS_NO_MEMORY</code></a>. Using
616 this nil object will cause its error state to propagate to other
617 objects it is passed to, (for example, calling
618 <a class="link" href="cairo-text.html#cairo-set-font-face" title="cairo_set_font_face ()"><code class="function">cairo_set_font_face()</code></a> with a nil font will trigger an error that
619 will shutdown the <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> object).</p>
620 </div>
621 <p class="since">Since: 1.0</p>
622 </div>
623 <hr>
624 <div class="refsect2">
625 <a name="cairo-set-scaled-font"></a><h3>cairo_set_scaled_font ()</h3>
626 <pre class="programlisting"><span class="returnvalue">void</span>
627 cairo_set_scaled_font (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
628 <em class="parameter"><code>const <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-t" title="cairo_scaled_font_t"><span class="type">cairo_scaled_font_t</span></a> *scaled_font</code></em>);</pre>
629 <p>Replaces the current font face, font matrix, and font options in
630 the <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> with those of the <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-t" title="cairo_scaled_font_t"><span class="type">cairo_scaled_font_t</span></a>. Except for
631 some translation, the current CTM of the <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> should be the
632 same as that of the <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-t" title="cairo_scaled_font_t"><span class="type">cairo_scaled_font_t</span></a>, which can be accessed
633 using <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-get-ctm" title="cairo_scaled_font_get_ctm ()"><code class="function">cairo_scaled_font_get_ctm()</code></a>.</p>
634 <div class="refsect3">
635 <a name="cairo-set-scaled-font.parameters"></a><h4>Parameters</h4>
636 <div class="informaltable"><table class="informaltable" width="100%" border="0">
637 <colgroup>
638 <col width="150px" class="parameters_name">
639 <col class="parameters_description">
640 <col width="200px" class="parameters_annotations">
641 </colgroup>
642 <tbody>
643 <tr>
644 <td class="parameter_name"><p>cr</p></td>
645 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
646 <td class="parameter_annotations"> </td>
647 </tr>
648 <tr>
649 <td class="parameter_name"><p>scaled_font</p></td>
650 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-t" title="cairo_scaled_font_t"><span class="type">cairo_scaled_font_t</span></a></p></td>
651 <td class="parameter_annotations"> </td>
652 </tr>
653 </tbody>
654 </table></div>
655 </div>
656 <p class="since">Since: 1.2</p>
657 </div>
658 <hr>
659 <div class="refsect2">
660 <a name="cairo-get-scaled-font"></a><h3>cairo_get_scaled_font ()</h3>
661 <pre class="programlisting"><a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-t" title="cairo_scaled_font_t"><span class="returnvalue">cairo_scaled_font_t</span></a> *
662 cairo_get_scaled_font (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>);</pre>
663 <p>Gets the current scaled font for a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a>.</p>
664 <div class="refsect3">
665 <a name="cairo-get-scaled-font.parameters"></a><h4>Parameters</h4>
666 <div class="informaltable"><table class="informaltable" width="100%" border="0">
667 <colgroup>
668 <col width="150px" class="parameters_name">
669 <col class="parameters_description">
670 <col width="200px" class="parameters_annotations">
671 </colgroup>
672 <tbody><tr>
673 <td class="parameter_name"><p>cr</p></td>
674 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
675 <td class="parameter_annotations"> </td>
676 </tr></tbody>
677 </table></div>
678 </div>
679 <div class="refsect3">
680 <a name="cairo-get-scaled-font.returns"></a><h4>Returns</h4>
681 <p> the current scaled font. This object is owned by
682 cairo. To keep a reference to it, you must call
683 <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-reference" title="cairo_scaled_font_reference ()"><code class="function">cairo_scaled_font_reference()</code></a>.</p>
684 <p>This function never returns <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. If memory cannot be allocated, a
685 special "nil" <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-t" title="cairo_scaled_font_t"><span class="type">cairo_scaled_font_t</span></a> object will be returned on which
686 <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-status" title="cairo_scaled_font_status ()"><code class="function">cairo_scaled_font_status()</code></a> returns <a class="link" href="cairo-Error-handling.html#CAIRO-STATUS-NO-MEMORY:CAPS"><code class="literal">CAIRO_STATUS_NO_MEMORY</code></a>. Using
687 this nil object will cause its error state to propagate to other
688 objects it is passed to, (for example, calling
689 <a class="link" href="cairo-text.html#cairo-set-scaled-font" title="cairo_set_scaled_font ()"><code class="function">cairo_set_scaled_font()</code></a> with a nil font will trigger an error that
690 will shutdown the <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> object).</p>
691 </div>
692 <p class="since">Since: 1.4</p>
693 </div>
694 <hr>
695 <div class="refsect2">
696 <a name="cairo-show-text"></a><h3>cairo_show_text ()</h3>
697 <pre class="programlisting"><span class="returnvalue">void</span>
698 cairo_show_text (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
699 <em class="parameter"><code>const <span class="type">char</span> *utf8</code></em>);</pre>
700 <p>A drawing operator that generates the shape from a string of UTF-8
701 characters, rendered according to the current font_face, font_size
702 (font_matrix), and font_options.</p>
703 <p>This function first computes a set of glyphs for the string of
704 text. The first glyph is placed so that its origin is at the
705 current point. The origin of each subsequent glyph is offset from
706 that of the previous glyph by the advance values of the previous
707 glyph.</p>
708 <p>After this call the current point is moved to the origin of where
709 the next glyph would be placed in this same progression. That is,
710 the current point will be at the origin of the final glyph offset
711 by its advance values. This allows for easy display of a single
712 logical string with multiple calls to <a class="link" href="cairo-text.html#cairo-show-text" title="cairo_show_text ()"><code class="function">cairo_show_text()</code></a>.</p>
713 <p>Note: The <a class="link" href="cairo-text.html#cairo-show-text" title="cairo_show_text ()"><code class="function">cairo_show_text()</code></a> function call is part of what the cairo
714 designers call the "toy" text API. It is convenient for short demos
715 and simple programs, but it is not expected to be adequate for
716 serious text-using applications. See <a class="link" href="cairo-text.html#cairo-show-glyphs" title="cairo_show_glyphs ()"><code class="function">cairo_show_glyphs()</code></a> for the
717 "real" text display API in cairo.</p>
718 <div class="refsect3">
719 <a name="cairo-show-text.parameters"></a><h4>Parameters</h4>
720 <div class="informaltable"><table class="informaltable" width="100%" border="0">
721 <colgroup>
722 <col width="150px" class="parameters_name">
723 <col class="parameters_description">
724 <col width="200px" class="parameters_annotations">
725 </colgroup>
726 <tbody>
727 <tr>
728 <td class="parameter_name"><p>cr</p></td>
729 <td class="parameter_description"><p>a cairo context</p></td>
730 <td class="parameter_annotations"> </td>
731 </tr>
732 <tr>
733 <td class="parameter_name"><p>utf8</p></td>
734 <td class="parameter_description"><p>a NUL-terminated string of text encoded in UTF-8, or <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td>
735 <td class="parameter_annotations"> </td>
736 </tr>
737 </tbody>
738 </table></div>
739 </div>
740 <p class="since">Since: 1.0</p>
741 </div>
742 <hr>
743 <div class="refsect2">
744 <a name="cairo-show-glyphs"></a><h3>cairo_show_glyphs ()</h3>
745 <pre class="programlisting"><span class="returnvalue">void</span>
746 cairo_show_glyphs (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
747 <em class="parameter"><code>const <a class="link" href="cairo-text.html#cairo-glyph-t" title="cairo_glyph_t"><span class="type">cairo_glyph_t</span></a> *glyphs</code></em>,
748 <em class="parameter"><code><span class="type">int</span> num_glyphs</code></em>);</pre>
749 <p>A drawing operator that generates the shape from an array of glyphs,
750 rendered according to the current font face, font size
751 (font matrix), and font options.</p>
752 <div class="refsect3">
753 <a name="cairo-show-glyphs.parameters"></a><h4>Parameters</h4>
754 <div class="informaltable"><table class="informaltable" width="100%" border="0">
755 <colgroup>
756 <col width="150px" class="parameters_name">
757 <col class="parameters_description">
758 <col width="200px" class="parameters_annotations">
759 </colgroup>
760 <tbody>
761 <tr>
762 <td class="parameter_name"><p>cr</p></td>
763 <td class="parameter_description"><p>a cairo context</p></td>
764 <td class="parameter_annotations"> </td>
765 </tr>
766 <tr>
767 <td class="parameter_name"><p>glyphs</p></td>
768 <td class="parameter_description"><p>array of glyphs to show</p></td>
769 <td class="parameter_annotations"> </td>
770 </tr>
771 <tr>
772 <td class="parameter_name"><p>num_glyphs</p></td>
773 <td class="parameter_description"><p>number of glyphs to show</p></td>
774 <td class="parameter_annotations"> </td>
775 </tr>
776 </tbody>
777 </table></div>
778 </div>
779 <p class="since">Since: 1.0</p>
780 </div>
781 <hr>
782 <div class="refsect2">
783 <a name="cairo-show-text-glyphs"></a><h3>cairo_show_text_glyphs ()</h3>
784 <pre class="programlisting"><span class="returnvalue">void</span>
785 cairo_show_text_glyphs (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
786 <em class="parameter"><code>const <span class="type">char</span> *utf8</code></em>,
787 <em class="parameter"><code><span class="type">int</span> utf8_len</code></em>,
788 <em class="parameter"><code>const <a class="link" href="cairo-text.html#cairo-glyph-t" title="cairo_glyph_t"><span class="type">cairo_glyph_t</span></a> *glyphs</code></em>,
789 <em class="parameter"><code><span class="type">int</span> num_glyphs</code></em>,
790 <em class="parameter"><code>const <a class="link" href="cairo-text.html#cairo-text-cluster-t" title="cairo_text_cluster_t"><span class="type">cairo_text_cluster_t</span></a> *clusters</code></em>,
791 <em class="parameter"><code><span class="type">int</span> num_clusters</code></em>,
792 <em class="parameter"><code><a class="link" href="cairo-text.html#cairo-text-cluster-flags-t" title="enum cairo_text_cluster_flags_t"><span class="type">cairo_text_cluster_flags_t</span></a> cluster_flags</code></em>);</pre>
793 <p>This operation has rendering effects similar to <a class="link" href="cairo-text.html#cairo-show-glyphs" title="cairo_show_glyphs ()"><code class="function">cairo_show_glyphs()</code></a>
794 but, if the target surface supports it, uses the provided text and
795 cluster mapping to embed the text for the glyphs shown in the output.
796 If the target does not support the extended attributes, this function
797 acts like the basic <a class="link" href="cairo-text.html#cairo-show-glyphs" title="cairo_show_glyphs ()"><code class="function">cairo_show_glyphs()</code></a> as if it had been passed
798 <em class="parameter"><code>glyphs</code></em>
799 and <em class="parameter"><code>num_glyphs</code></em>
800 .</p>
801 <p>The mapping between <em class="parameter"><code>utf8</code></em>
802 and <em class="parameter"><code>glyphs</code></em>
803 is provided by an array of
804 <em class="firstterm">clusters</em>. Each cluster covers a number of
805 text bytes and glyphs, and neighboring clusters cover neighboring
806 areas of <em class="parameter"><code>utf8</code></em>
807 and <em class="parameter"><code>glyphs</code></em>
808 . The clusters should collectively cover <em class="parameter"><code>utf8</code></em>
809
810 and <em class="parameter"><code>glyphs</code></em>
811 in entirety.</p>
812 <p>The first cluster always covers bytes from the beginning of <em class="parameter"><code>utf8</code></em>
813 .
814 If <em class="parameter"><code>cluster_flags</code></em>
815 do not have the <a class="link" href="cairo-text.html#CAIRO-TEXT-CLUSTER-FLAG-BACKWARD:CAPS"><code class="literal">CAIRO_TEXT_CLUSTER_FLAG_BACKWARD</code></a>
816 set, the first cluster also covers the beginning
817 of <em class="parameter"><code>glyphs</code></em>
818 , otherwise it covers the end of the <em class="parameter"><code>glyphs</code></em>
819 array and
820 following clusters move backward.</p>
821 <p>See <a class="link" href="cairo-text.html#cairo-text-cluster-t" title="cairo_text_cluster_t"><span class="type">cairo_text_cluster_t</span></a> for constraints on valid clusters.</p>
822 <div class="refsect3">
823 <a name="cairo-show-text-glyphs.parameters"></a><h4>Parameters</h4>
824 <div class="informaltable"><table class="informaltable" width="100%" border="0">
825 <colgroup>
826 <col width="150px" class="parameters_name">
827 <col class="parameters_description">
828 <col width="200px" class="parameters_annotations">
829 </colgroup>
830 <tbody>
831 <tr>
832 <td class="parameter_name"><p>cr</p></td>
833 <td class="parameter_description"><p>a cairo context</p></td>
834 <td class="parameter_annotations"> </td>
835 </tr>
836 <tr>
837 <td class="parameter_name"><p>utf8</p></td>
838 <td class="parameter_description"><p>a string of text encoded in UTF-8</p></td>
839 <td class="parameter_annotations"> </td>
840 </tr>
841 <tr>
842 <td class="parameter_name"><p>utf8_len</p></td>
843 <td class="parameter_description"><p>length of <em class="parameter"><code>utf8</code></em>
844 in bytes, or -1 if it is NUL-terminated</p></td>
845 <td class="parameter_annotations"> </td>
846 </tr>
847 <tr>
848 <td class="parameter_name"><p>glyphs</p></td>
849 <td class="parameter_description"><p>array of glyphs to show</p></td>
850 <td class="parameter_annotations"> </td>
851 </tr>
852 <tr>
853 <td class="parameter_name"><p>num_glyphs</p></td>
854 <td class="parameter_description"><p>number of glyphs to show</p></td>
855 <td class="parameter_annotations"> </td>
856 </tr>
857 <tr>
858 <td class="parameter_name"><p>clusters</p></td>
859 <td class="parameter_description"><p>array of cluster mapping information</p></td>
860 <td class="parameter_annotations"> </td>
861 </tr>
862 <tr>
863 <td class="parameter_name"><p>num_clusters</p></td>
864 <td class="parameter_description"><p>number of clusters in the mapping</p></td>
865 <td class="parameter_annotations"> </td>
866 </tr>
867 <tr>
868 <td class="parameter_name"><p>cluster_flags</p></td>
869 <td class="parameter_description"><p>cluster mapping flags</p></td>
870 <td class="parameter_annotations"> </td>
871 </tr>
872 </tbody>
873 </table></div>
874 </div>
875 <p class="since">Since: 1.8</p>
876 </div>
877 <hr>
878 <div class="refsect2">
879 <a name="cairo-font-extents"></a><h3>cairo_font_extents ()</h3>
880 <pre class="programlisting"><span class="returnvalue">void</span>
881 cairo_font_extents (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
882 <em class="parameter"><code><a class="link" href="cairo-cairo-scaled-font-t.html#cairo-font-extents-t" title="cairo_font_extents_t"><span class="type">cairo_font_extents_t</span></a> *extents</code></em>);</pre>
883 <p>Gets the font extents for the currently selected font.</p>
884 <div class="refsect3">
885 <a name="cairo-font-extents.parameters"></a><h4>Parameters</h4>
886 <div class="informaltable"><table class="informaltable" width="100%" border="0">
887 <colgroup>
888 <col width="150px" class="parameters_name">
889 <col class="parameters_description">
890 <col width="200px" class="parameters_annotations">
891 </colgroup>
892 <tbody>
893 <tr>
894 <td class="parameter_name"><p>cr</p></td>
895 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
896 <td class="parameter_annotations"> </td>
897 </tr>
898 <tr>
899 <td class="parameter_name"><p>extents</p></td>
900 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-font-extents-t" title="cairo_font_extents_t"><span class="type">cairo_font_extents_t</span></a> object into which the results
901 will be stored.</p></td>
902 <td class="parameter_annotations"> </td>
903 </tr>
904 </tbody>
905 </table></div>
906 </div>
907 <p class="since">Since: 1.0</p>
908 </div>
909 <hr>
910 <div class="refsect2">
911 <a name="cairo-text-extents"></a><h3>cairo_text_extents ()</h3>
912 <pre class="programlisting"><span class="returnvalue">void</span>
913 cairo_text_extents (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
914 <em class="parameter"><code>const <span class="type">char</span> *utf8</code></em>,
915 <em class="parameter"><code><a class="link" href="cairo-cairo-scaled-font-t.html#cairo-text-extents-t" title="cairo_text_extents_t"><span class="type">cairo_text_extents_t</span></a> *extents</code></em>);</pre>
916 <p>Gets the extents for a string of text. The extents describe a
917 user-space rectangle that encloses the "inked" portion of the text,
918 (as it would be drawn by <a class="link" href="cairo-text.html#cairo-show-text" title="cairo_show_text ()"><code class="function">cairo_show_text()</code></a>). Additionally, the
919 x_advance and y_advance values indicate the amount by which the
920 current point would be advanced by <a class="link" href="cairo-text.html#cairo-show-text" title="cairo_show_text ()"><code class="function">cairo_show_text()</code></a>.</p>
921 <p>Note that whitespace characters do not directly contribute to the
922 size of the rectangle (extents.width and extents.height). They do
923 contribute indirectly by changing the position of non-whitespace
924 characters. In particular, trailing whitespace characters are
925 likely to not affect the size of the rectangle, though they will
926 affect the x_advance and y_advance values.</p>
927 <div class="refsect3">
928 <a name="cairo-text-extents.parameters"></a><h4>Parameters</h4>
929 <div class="informaltable"><table class="informaltable" width="100%" border="0">
930 <colgroup>
931 <col width="150px" class="parameters_name">
932 <col class="parameters_description">
933 <col width="200px" class="parameters_annotations">
934 </colgroup>
935 <tbody>
936 <tr>
937 <td class="parameter_name"><p>cr</p></td>
938 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
939 <td class="parameter_annotations"> </td>
940 </tr>
941 <tr>
942 <td class="parameter_name"><p>utf8</p></td>
943 <td class="parameter_description"><p>a NUL-terminated string of text encoded in UTF-8, or <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td>
944 <td class="parameter_annotations"> </td>
945 </tr>
946 <tr>
947 <td class="parameter_name"><p>extents</p></td>
948 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-text-extents-t" title="cairo_text_extents_t"><span class="type">cairo_text_extents_t</span></a> object into which the results
949 will be stored</p></td>
950 <td class="parameter_annotations"> </td>
951 </tr>
952 </tbody>
953 </table></div>
954 </div>
955 <p class="since">Since: 1.0</p>
956 </div>
957 <hr>
958 <div class="refsect2">
959 <a name="cairo-glyph-extents"></a><h3>cairo_glyph_extents ()</h3>
960 <pre class="programlisting"><span class="returnvalue">void</span>
961 cairo_glyph_extents (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
962 <em class="parameter"><code>const <a class="link" href="cairo-text.html#cairo-glyph-t" title="cairo_glyph_t"><span class="type">cairo_glyph_t</span></a> *glyphs</code></em>,
963 <em class="parameter"><code><span class="type">int</span> num_glyphs</code></em>,
964 <em class="parameter"><code><a class="link" href="cairo-cairo-scaled-font-t.html#cairo-text-extents-t" title="cairo_text_extents_t"><span class="type">cairo_text_extents_t</span></a> *extents</code></em>);</pre>
965 <p>Gets the extents for an array of glyphs. The extents describe a
966 user-space rectangle that encloses the "inked" portion of the
967 glyphs, (as they would be drawn by <a class="link" href="cairo-text.html#cairo-show-glyphs" title="cairo_show_glyphs ()"><code class="function">cairo_show_glyphs()</code></a>).
968 Additionally, the x_advance and y_advance values indicate the
969 amount by which the current point would be advanced by
970 <a class="link" href="cairo-text.html#cairo-show-glyphs" title="cairo_show_glyphs ()"><code class="function">cairo_show_glyphs()</code></a>.</p>
971 <p>Note that whitespace glyphs do not contribute to the size of the
972 rectangle (extents.width and extents.height).</p>
973 <div class="refsect3">
974 <a name="cairo-glyph-extents.parameters"></a><h4>Parameters</h4>
975 <div class="informaltable"><table class="informaltable" width="100%" border="0">
976 <colgroup>
977 <col width="150px" class="parameters_name">
978 <col class="parameters_description">
979 <col width="200px" class="parameters_annotations">
980 </colgroup>
981 <tbody>
982 <tr>
983 <td class="parameter_name"><p>cr</p></td>
984 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a></p></td>
985 <td class="parameter_annotations"> </td>
986 </tr>
987 <tr>
988 <td class="parameter_name"><p>glyphs</p></td>
989 <td class="parameter_description"><p>an array of <a class="link" href="cairo-text.html#cairo-glyph-t" title="cairo_glyph_t"><span class="type">cairo_glyph_t</span></a> objects</p></td>
990 <td class="parameter_annotations"> </td>
991 </tr>
992 <tr>
993 <td class="parameter_name"><p>num_glyphs</p></td>
994 <td class="parameter_description"><p>the number of elements in <em class="parameter"><code>glyphs</code></em>
995 </p></td>
996 <td class="parameter_annotations"> </td>
997 </tr>
998 <tr>
999 <td class="parameter_name"><p>extents</p></td>
1000 <td class="parameter_description"><p>a <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-text-extents-t" title="cairo_text_extents_t"><span class="type">cairo_text_extents_t</span></a> object into which the results
1001 will be stored</p></td>
1002 <td class="parameter_annotations"> </td>
1003 </tr>
1004 </tbody>
1005 </table></div>
1006 </div>
1007 <p class="since">Since: 1.0</p>
1008 </div>
1009 <hr>
1010 <div class="refsect2">
1011 <a name="cairo-toy-font-face-create"></a><h3>cairo_toy_font_face_create ()</h3>
1012 <pre class="programlisting"><a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="returnvalue">cairo_font_face_t</span></a> *
1013 cairo_toy_font_face_create (<em class="parameter"><code>const <span class="type">char</span> *family</code></em>,
1014 <em class="parameter"><code><a class="link" href="cairo-text.html#cairo-font-slant-t" title="enum cairo_font_slant_t"><span class="type">cairo_font_slant_t</span></a> slant</code></em>,
1015 <em class="parameter"><code><a class="link" href="cairo-text.html#cairo-font-weight-t" title="enum cairo_font_weight_t"><span class="type">cairo_font_weight_t</span></a> weight</code></em>);</pre>
1016 <p>Creates a font face from a triplet of family, slant, and weight.
1017 These font faces are used in implementation of the the <a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> "toy"
1018 font API.</p>
1019 <p>If <em class="parameter"><code>family</code></em>
1020 is the zero-length string "", the platform-specific default
1021 family is assumed. The default family then can be queried using
1022 <a class="link" href="cairo-text.html#cairo-toy-font-face-get-family" title="cairo_toy_font_face_get_family ()"><code class="function">cairo_toy_font_face_get_family()</code></a>.</p>
1023 <p>The <a class="link" href="cairo-text.html#cairo-select-font-face" title="cairo_select_font_face ()"><code class="function">cairo_select_font_face()</code></a> function uses this to create font faces.
1024 See that function for limitations and other details of toy font faces.</p>
1025 <div class="refsect3">
1026 <a name="cairo-toy-font-face-create.parameters"></a><h4>Parameters</h4>
1027 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1028 <colgroup>
1029 <col width="150px" class="parameters_name">
1030 <col class="parameters_description">
1031 <col width="200px" class="parameters_annotations">
1032 </colgroup>
1033 <tbody>
1034 <tr>
1035 <td class="parameter_name"><p>family</p></td>
1036 <td class="parameter_description"><p>a font family name, encoded in UTF-8</p></td>
1037 <td class="parameter_annotations"> </td>
1038 </tr>
1039 <tr>
1040 <td class="parameter_name"><p>slant</p></td>
1041 <td class="parameter_description"><p>the slant for the font</p></td>
1042 <td class="parameter_annotations"> </td>
1043 </tr>
1044 <tr>
1045 <td class="parameter_name"><p>weight</p></td>
1046 <td class="parameter_description"><p>the weight for the font</p></td>
1047 <td class="parameter_annotations"> </td>
1048 </tr>
1049 </tbody>
1050 </table></div>
1051 </div>
1052 <div class="refsect3">
1053 <a name="cairo-toy-font-face-create.returns"></a><h4>Returns</h4>
1054 <p> a newly created <a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="type">cairo_font_face_t</span></a>. Free with
1055 <a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-destroy" title="cairo_font_face_destroy ()"><code class="function">cairo_font_face_destroy()</code></a> when you are done using it.</p>
1056 </div>
1057 <p class="since">Since: 1.8</p>
1058 </div>
1059 <hr>
1060 <div class="refsect2">
1061 <a name="cairo-toy-font-face-get-family"></a><h3>cairo_toy_font_face_get_family ()</h3>
1062 <pre class="programlisting">const <span class="returnvalue">char</span> *
1063 cairo_toy_font_face_get_family (<em class="parameter"><code><a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="type">cairo_font_face_t</span></a> *font_face</code></em>);</pre>
1064 <p>Gets the familly name of a toy font.</p>
1065 <div class="refsect3">
1066 <a name="cairo-toy-font-face-get-family.parameters"></a><h4>Parameters</h4>
1067 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1068 <colgroup>
1069 <col width="150px" class="parameters_name">
1070 <col class="parameters_description">
1071 <col width="200px" class="parameters_annotations">
1072 </colgroup>
1073 <tbody><tr>
1074 <td class="parameter_name"><p>font_face</p></td>
1075 <td class="parameter_description"><p>A toy font face</p></td>
1076 <td class="parameter_annotations"> </td>
1077 </tr></tbody>
1078 </table></div>
1079 </div>
1080 <div class="refsect3">
1081 <a name="cairo-toy-font-face-get-family.returns"></a><h4>Returns</h4>
1082 <p> The family name. This string is owned by the font face
1083 and remains valid as long as the font face is alive (referenced).</p>
1084 </div>
1085 <p class="since">Since: 1.8</p>
1086 </div>
1087 <hr>
1088 <div class="refsect2">
1089 <a name="cairo-toy-font-face-get-slant"></a><h3>cairo_toy_font_face_get_slant ()</h3>
1090 <pre class="programlisting"><a class="link" href="cairo-text.html#cairo-font-slant-t" title="enum cairo_font_slant_t"><span class="returnvalue">cairo_font_slant_t</span></a>
1091 cairo_toy_font_face_get_slant (<em class="parameter"><code><a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="type">cairo_font_face_t</span></a> *font_face</code></em>);</pre>
1092 <p>Gets the slant a toy font.</p>
1093 <div class="refsect3">
1094 <a name="cairo-toy-font-face-get-slant.parameters"></a><h4>Parameters</h4>
1095 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1096 <colgroup>
1097 <col width="150px" class="parameters_name">
1098 <col class="parameters_description">
1099 <col width="200px" class="parameters_annotations">
1100 </colgroup>
1101 <tbody><tr>
1102 <td class="parameter_name"><p>font_face</p></td>
1103 <td class="parameter_description"><p>A toy font face</p></td>
1104 <td class="parameter_annotations"> </td>
1105 </tr></tbody>
1106 </table></div>
1107 </div>
1108 <div class="refsect3">
1109 <a name="cairo-toy-font-face-get-slant.returns"></a><h4>Returns</h4>
1110 <p> The slant value</p>
1111 </div>
1112 <p class="since">Since: 1.8</p>
1113 </div>
1114 <hr>
1115 <div class="refsect2">
1116 <a name="cairo-toy-font-face-get-weight"></a><h3>cairo_toy_font_face_get_weight ()</h3>
1117 <pre class="programlisting"><a class="link" href="cairo-text.html#cairo-font-weight-t" title="enum cairo_font_weight_t"><span class="returnvalue">cairo_font_weight_t</span></a>
1118 cairo_toy_font_face_get_weight (<em class="parameter"><code><a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="type">cairo_font_face_t</span></a> *font_face</code></em>);</pre>
1119 <p>Gets the weight a toy font.</p>
1120 <div class="refsect3">
1121 <a name="cairo-toy-font-face-get-weight.parameters"></a><h4>Parameters</h4>
1122 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1123 <colgroup>
1124 <col width="150px" class="parameters_name">
1125 <col class="parameters_description">
1126 <col width="200px" class="parameters_annotations">
1127 </colgroup>
1128 <tbody><tr>
1129 <td class="parameter_name"><p>font_face</p></td>
1130 <td class="parameter_description"><p>A toy font face</p></td>
1131 <td class="parameter_annotations"> </td>
1132 </tr></tbody>
1133 </table></div>
1134 </div>
1135 <div class="refsect3">
1136 <a name="cairo-toy-font-face-get-weight.returns"></a><h4>Returns</h4>
1137 <p> The weight value</p>
1138 </div>
1139 <p class="since">Since: 1.8</p>
1140 </div>
1141 <hr>
1142 <div class="refsect2">
1143 <a name="cairo-glyph-allocate"></a><h3>cairo_glyph_allocate ()</h3>
1144 <pre class="programlisting"><a class="link" href="cairo-text.html#cairo-glyph-t" title="cairo_glyph_t"><span class="returnvalue">cairo_glyph_t</span></a> *
1145 cairo_glyph_allocate (<em class="parameter"><code><span class="type">int</span> num_glyphs</code></em>);</pre>
1146 <p>Allocates an array of <a class="link" href="cairo-text.html#cairo-glyph-t" title="cairo_glyph_t"><span class="type">cairo_glyph_t</span></a>'s.
1147 This function is only useful in implementations of
1148 <a class="link" href="cairo-User-Fonts.html#cairo-user-scaled-font-text-to-glyphs-func-t" title="cairo_user_scaled_font_text_to_glyphs_func_t ()"><span class="type">cairo_user_scaled_font_text_to_glyphs_func_t</span></a> where the user
1149 needs to allocate an array of glyphs that cairo will free.
1150 For all other uses, user can use their own allocation method
1151 for glyphs.</p>
1152 <p>This function returns <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if <em class="parameter"><code>num_glyphs</code></em>
1153 is not positive,
1154 or if out of memory. That means, the <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> return value
1155 signals out-of-memory only if <em class="parameter"><code>num_glyphs</code></em>
1156 was positive.</p>
1157 <div class="refsect3">
1158 <a name="cairo-glyph-allocate.parameters"></a><h4>Parameters</h4>
1159 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1160 <colgroup>
1161 <col width="150px" class="parameters_name">
1162 <col class="parameters_description">
1163 <col width="200px" class="parameters_annotations">
1164 </colgroup>
1165 <tbody><tr>
1166 <td class="parameter_name"><p>num_glyphs</p></td>
1167 <td class="parameter_description"><p>number of glyphs to allocate</p></td>
1168 <td class="parameter_annotations"> </td>
1169 </tr></tbody>
1170 </table></div>
1171 </div>
1172 <div class="refsect3">
1173 <a name="cairo-glyph-allocate.returns"></a><h4>Returns</h4>
1174 <p> the newly allocated array of glyphs that should be
1175 freed using <a class="link" href="cairo-text.html#cairo-glyph-free" title="cairo_glyph_free ()"><code class="function">cairo_glyph_free()</code></a></p>
1176 </div>
1177 <p class="since">Since: 1.8</p>
1178 </div>
1179 <hr>
1180 <div class="refsect2">
1181 <a name="cairo-glyph-free"></a><h3>cairo_glyph_free ()</h3>
1182 <pre class="programlisting"><span class="returnvalue">void</span>
1183 cairo_glyph_free (<em class="parameter"><code><a class="link" href="cairo-text.html#cairo-glyph-t" title="cairo_glyph_t"><span class="type">cairo_glyph_t</span></a> *glyphs</code></em>);</pre>
1184 <p>Frees an array of <a class="link" href="cairo-text.html#cairo-glyph-t" title="cairo_glyph_t"><span class="type">cairo_glyph_t</span></a>'s allocated using <a class="link" href="cairo-text.html#cairo-glyph-allocate" title="cairo_glyph_allocate ()"><code class="function">cairo_glyph_allocate()</code></a>.
1185 This function is only useful to free glyph array returned
1186 by <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-text-to-glyphs" title="cairo_scaled_font_text_to_glyphs ()"><code class="function">cairo_scaled_font_text_to_glyphs()</code></a> where cairo returns
1187 an array of glyphs that the user will free.
1188 For all other uses, user can use their own allocation method
1189 for glyphs.</p>
1190 <div class="refsect3">
1191 <a name="cairo-glyph-free.parameters"></a><h4>Parameters</h4>
1192 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1193 <colgroup>
1194 <col width="150px" class="parameters_name">
1195 <col class="parameters_description">
1196 <col width="200px" class="parameters_annotations">
1197 </colgroup>
1198 <tbody><tr>
1199 <td class="parameter_name"><p>glyphs</p></td>
1200 <td class="parameter_description"><p>array of glyphs to free, or <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td>
1201 <td class="parameter_annotations"> </td>
1202 </tr></tbody>
1203 </table></div>
1204 </div>
1205 <p class="since">Since: 1.8</p>
1206 </div>
1207 <hr>
1208 <div class="refsect2">
1209 <a name="cairo-text-cluster-allocate"></a><h3>cairo_text_cluster_allocate ()</h3>
1210 <pre class="programlisting"><a class="link" href="cairo-text.html#cairo-text-cluster-t" title="cairo_text_cluster_t"><span class="returnvalue">cairo_text_cluster_t</span></a> *
1211 cairo_text_cluster_allocate (<em class="parameter"><code><span class="type">int</span> num_clusters</code></em>);</pre>
1212 <p>Allocates an array of <a class="link" href="cairo-text.html#cairo-text-cluster-t" title="cairo_text_cluster_t"><span class="type">cairo_text_cluster_t</span></a>'s.
1213 This function is only useful in implementations of
1214 <a class="link" href="cairo-User-Fonts.html#cairo-user-scaled-font-text-to-glyphs-func-t" title="cairo_user_scaled_font_text_to_glyphs_func_t ()"><span class="type">cairo_user_scaled_font_text_to_glyphs_func_t</span></a> where the user
1215 needs to allocate an array of text clusters that cairo will free.
1216 For all other uses, user can use their own allocation method
1217 for text clusters.</p>
1218 <p>This function returns <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if <em class="parameter"><code>num_clusters</code></em>
1219 is not positive,
1220 or if out of memory. That means, the <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> return value
1221 signals out-of-memory only if <em class="parameter"><code>num_clusters</code></em>
1222 was positive.</p>
1223 <div class="refsect3">
1224 <a name="cairo-text-cluster-allocate.parameters"></a><h4>Parameters</h4>
1225 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1226 <colgroup>
1227 <col width="150px" class="parameters_name">
1228 <col class="parameters_description">
1229 <col width="200px" class="parameters_annotations">
1230 </colgroup>
1231 <tbody><tr>
1232 <td class="parameter_name"><p>num_clusters</p></td>
1233 <td class="parameter_description"><p>number of text_clusters to allocate</p></td>
1234 <td class="parameter_annotations"> </td>
1235 </tr></tbody>
1236 </table></div>
1237 </div>
1238 <div class="refsect3">
1239 <a name="cairo-text-cluster-allocate.returns"></a><h4>Returns</h4>
1240 <p> the newly allocated array of text clusters that should be
1241 freed using <a class="link" href="cairo-text.html#cairo-text-cluster-free" title="cairo_text_cluster_free ()"><code class="function">cairo_text_cluster_free()</code></a></p>
1242 </div>
1243 <p class="since">Since: 1.8</p>
1244 </div>
1245 <hr>
1246 <div class="refsect2">
1247 <a name="cairo-text-cluster-free"></a><h3>cairo_text_cluster_free ()</h3>
1248 <pre class="programlisting"><span class="returnvalue">void</span>
1249 cairo_text_cluster_free (<em class="parameter"><code><a class="link" href="cairo-text.html#cairo-text-cluster-t" title="cairo_text_cluster_t"><span class="type">cairo_text_cluster_t</span></a> *clusters</code></em>);</pre>
1250 <p>Frees an array of <span class="type">cairo_text_cluster</span>'s allocated using <a class="link" href="cairo-text.html#cairo-text-cluster-allocate" title="cairo_text_cluster_allocate ()"><code class="function">cairo_text_cluster_allocate()</code></a>.
1251 This function is only useful to free text cluster array returned
1252 by <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-text-to-glyphs" title="cairo_scaled_font_text_to_glyphs ()"><code class="function">cairo_scaled_font_text_to_glyphs()</code></a> where cairo returns
1253 an array of text clusters that the user will free.
1254 For all other uses, user can use their own allocation method
1255 for text clusters.</p>
1256 <div class="refsect3">
1257 <a name="cairo-text-cluster-free.parameters"></a><h4>Parameters</h4>
1258 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1259 <colgroup>
1260 <col width="150px" class="parameters_name">
1261 <col class="parameters_description">
1262 <col width="200px" class="parameters_annotations">
1263 </colgroup>
1264 <tbody><tr>
1265 <td class="parameter_name"><p>clusters</p></td>
1266 <td class="parameter_description"><p>array of text clusters to free, or <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td>
1267 <td class="parameter_annotations"> </td>
1268 </tr></tbody>
1269 </table></div>
1270 </div>
1271 <p class="since">Since: 1.8</p>
1272 </div>
1273 </div>
1274 <div class="refsect1">
1275 <a name="cairo-text.other_details"></a><h2>Types and Values</h2>
1276 <div class="refsect2">
1277 <a name="cairo-glyph-t"></a><h3>cairo_glyph_t</h3>
1278 <pre class="programlisting">typedef struct {
1279 unsigned long index;
1280 double x;
1281 double y;
1282 } cairo_glyph_t;
1283 </pre>
1284 <p>The <a class="link" href="cairo-text.html#cairo-glyph-t" title="cairo_glyph_t"><span class="type">cairo_glyph_t</span></a> structure holds information about a single glyph
1285 when drawing or measuring text. A font is (in simple terms) a
1286 collection of shapes used to draw text. A glyph is one of these
1287 shapes. There can be multiple glyphs for a single character
1288 (alternates to be used in different contexts, for example), or a
1289 glyph can be a <em class="firstterm">ligature</em> of multiple
1290 characters. Cairo doesn't expose any way of converting input text
1291 into glyphs, so in order to use the Cairo interfaces that take
1292 arrays of glyphs, you must directly access the appropriate
1293 underlying font system.</p>
1294 <p>Note that the offsets given by <em class="parameter"><code>x</code></em>
1295 and <em class="parameter"><code>y</code></em>
1296 are not cumulative. When
1297 drawing or measuring text, each glyph is individually positioned
1298 with respect to the overall origin</p>
1299 <div class="refsect3">
1300 <a name="cairo-glyph-t.members"></a><h4>Members</h4>
1301 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1302 <colgroup>
1303 <col width="300px" class="struct_members_name">
1304 <col class="struct_members_description">
1305 <col width="200px" class="struct_members_annotations">
1306 </colgroup>
1307 <tbody>
1308 <tr>
1309 <td class="struct_member_name"><p>unsigned <span class="type">long</span> <em class="structfield"><code><a name="cairo-glyph-t.index"></a>index</code></em>;</p></td>
1310 <td class="struct_member_description"><p>glyph index in the font. The exact interpretation of the
1311 glyph index depends on the font technology being used.</p></td>
1312 <td class="struct_member_annotations"> </td>
1313 </tr>
1314 <tr>
1315 <td class="struct_member_name"><p><span class="type">double</span> <em class="structfield"><code><a name="cairo-glyph-t.x"></a>x</code></em>;</p></td>
1316 <td class="struct_member_description"><p>the offset in the X direction between the origin used for
1317 drawing or measuring the string and the origin of this glyph.</p></td>
1318 <td class="struct_member_annotations"> </td>
1319 </tr>
1320 <tr>
1321 <td class="struct_member_name"><p><span class="type">double</span> <em class="structfield"><code><a name="cairo-glyph-t.y"></a>y</code></em>;</p></td>
1322 <td class="struct_member_description"><p>the offset in the Y direction between the origin used for
1323 drawing or measuring the string and the origin of this glyph.</p></td>
1324 <td class="struct_member_annotations"> </td>
1325 </tr>
1326 </tbody>
1327 </table></div>
1328 </div>
1329 <p class="since">Since: 1.0</p>
1330 </div>
1331 <hr>
1332 <div class="refsect2">
1333 <a name="cairo-font-slant-t"></a><h3>enum cairo_font_slant_t</h3>
1334 <p>Specifies variants of a font face based on their slant.</p>
1335 <div class="refsect3">
1336 <a name="cairo-font-slant-t.members"></a><h4>Members</h4>
1337 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1338 <colgroup>
1339 <col width="300px" class="enum_members_name">
1340 <col class="enum_members_description">
1341 <col width="200px" class="enum_members_annotations">
1342 </colgroup>
1343 <tbody>
1344 <tr>
1345 <td class="enum_member_name"><p><a name="CAIRO-FONT-SLANT-NORMAL:CAPS"></a>CAIRO_FONT_SLANT_NORMAL</p></td>
1346 <td class="enum_member_description">
1347 <p>Upright font style, since 1.0</p>
1348 </td>
1349 <td class="enum_member_annotations"> </td>
1350 </tr>
1351 <tr>
1352 <td class="enum_member_name"><p><a name="CAIRO-FONT-SLANT-ITALIC:CAPS"></a>CAIRO_FONT_SLANT_ITALIC</p></td>
1353 <td class="enum_member_description">
1354 <p>Italic font style, since 1.0</p>
1355 </td>
1356 <td class="enum_member_annotations"> </td>
1357 </tr>
1358 <tr>
1359 <td class="enum_member_name"><p><a name="CAIRO-FONT-SLANT-OBLIQUE:CAPS"></a>CAIRO_FONT_SLANT_OBLIQUE</p></td>
1360 <td class="enum_member_description">
1361 <p>Oblique font style, since 1.0</p>
1362 </td>
1363 <td class="enum_member_annotations"> </td>
1364 </tr>
1365 </tbody>
1366 </table></div>
1367 </div>
1368 <p class="since">Since: 1.0</p>
1369 </div>
1370 <hr>
1371 <div class="refsect2">
1372 <a name="cairo-font-weight-t"></a><h3>enum cairo_font_weight_t</h3>
1373 <p>Specifies variants of a font face based on their weight.</p>
1374 <div class="refsect3">
1375 <a name="cairo-font-weight-t.members"></a><h4>Members</h4>
1376 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1377 <colgroup>
1378 <col width="300px" class="enum_members_name">
1379 <col class="enum_members_description">
1380 <col width="200px" class="enum_members_annotations">
1381 </colgroup>
1382 <tbody>
1383 <tr>
1384 <td class="enum_member_name"><p><a name="CAIRO-FONT-WEIGHT-NORMAL:CAPS"></a>CAIRO_FONT_WEIGHT_NORMAL</p></td>
1385 <td class="enum_member_description">
1386 <p>Normal font weight, since 1.0</p>
1387 </td>
1388 <td class="enum_member_annotations"> </td>
1389 </tr>
1390 <tr>
1391 <td class="enum_member_name"><p><a name="CAIRO-FONT-WEIGHT-BOLD:CAPS"></a>CAIRO_FONT_WEIGHT_BOLD</p></td>
1392 <td class="enum_member_description">
1393 <p>Bold font weight, since 1.0</p>
1394 </td>
1395 <td class="enum_member_annotations"> </td>
1396 </tr>
1397 </tbody>
1398 </table></div>
1399 </div>
1400 <p class="since">Since: 1.0</p>
1401 </div>
1402 <hr>
1403 <div class="refsect2">
1404 <a name="cairo-text-cluster-t"></a><h3>cairo_text_cluster_t</h3>
1405 <pre class="programlisting">typedef struct {
1406 int num_bytes;
1407 int num_glyphs;
1408 } cairo_text_cluster_t;
1409 </pre>
1410 <p>The <a class="link" href="cairo-text.html#cairo-text-cluster-t" title="cairo_text_cluster_t"><span class="type">cairo_text_cluster_t</span></a> structure holds information about a single
1411 <em class="firstterm">text cluster</em>. A text cluster is a minimal
1412 mapping of some glyphs corresponding to some UTF-8 text.</p>
1413 <p>For a cluster to be valid, both <em class="parameter"><code>num_bytes</code></em>
1414 and <em class="parameter"><code>num_glyphs</code></em>
1415 should
1416 be non-negative, and at least one should be non-zero.
1417 Note that clusters with zero glyphs are not as well supported as
1418 normal clusters. For example, PDF rendering applications typically
1419 ignore those clusters when PDF text is being selected.</p>
1420 <p>See <a class="link" href="cairo-text.html#cairo-show-text-glyphs" title="cairo_show_text_glyphs ()"><code class="function">cairo_show_text_glyphs()</code></a> for how clusters are used in advanced
1421 text operations.</p>
1422 <div class="refsect3">
1423 <a name="cairo-text-cluster-t.members"></a><h4>Members</h4>
1424 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1425 <colgroup>
1426 <col width="300px" class="struct_members_name">
1427 <col class="struct_members_description">
1428 <col width="200px" class="struct_members_annotations">
1429 </colgroup>
1430 <tbody>
1431 <tr>
1432 <td class="struct_member_name"><p><span class="type">int</span> <em class="structfield"><code><a name="cairo-text-cluster-t.num-bytes"></a>num_bytes</code></em>;</p></td>
1433 <td class="struct_member_description"><p>the number of bytes of UTF-8 text covered by cluster</p></td>
1434 <td class="struct_member_annotations"> </td>
1435 </tr>
1436 <tr>
1437 <td class="struct_member_name"><p><span class="type">int</span> <em class="structfield"><code><a name="cairo-text-cluster-t.num-glyphs"></a>num_glyphs</code></em>;</p></td>
1438 <td class="struct_member_description"><p>the number of glyphs covered by cluster</p></td>
1439 <td class="struct_member_annotations"> </td>
1440 </tr>
1441 </tbody>
1442 </table></div>
1443 </div>
1444 <p class="since">Since: 1.8</p>
1445 </div>
1446 <hr>
1447 <div class="refsect2">
1448 <a name="cairo-text-cluster-flags-t"></a><h3>enum cairo_text_cluster_flags_t</h3>
1449 <p>Specifies properties of a text cluster mapping.</p>
1450 <div class="refsect3">
1451 <a name="cairo-text-cluster-flags-t.members"></a><h4>Members</h4>
1452 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1453 <colgroup>
1454 <col width="300px" class="enum_members_name">
1455 <col class="enum_members_description">
1456 <col width="200px" class="enum_members_annotations">
1457 </colgroup>
1458 <tbody><tr>
1459 <td class="enum_member_name"><p><a name="CAIRO-TEXT-CLUSTER-FLAG-BACKWARD:CAPS"></a>CAIRO_TEXT_CLUSTER_FLAG_BACKWARD</p></td>
1460 <td class="enum_member_description">
1461 <p>The clusters in the cluster array
1462 map to glyphs in the glyph array from end to start. (Since 1.8)</p>
1463 </td>
1464 <td class="enum_member_annotations"> </td>
1465 </tr></tbody>
1466 </table></div>
1467 </div>
1468 <p class="since">Since: 1.8</p>
1469 </div>
1470 </div>
1471 <div class="refsect1">
1472 <a name="cairo-text.see-also"></a><h2>See Also</h2>
1473 <p><a class="link" href="cairo-cairo-font-face-t.html#cairo-font-face-t" title="cairo_font_face_t"><span class="type">cairo_font_face_t</span></a>, <a class="link" href="cairo-cairo-scaled-font-t.html#cairo-scaled-font-t" title="cairo_scaled_font_t"><span class="type">cairo_scaled_font_t</span></a>, <a class="link" href="cairo-Paths.html#cairo-text-path" title="cairo_text_path ()"><code class="function">cairo_text_path()</code></a>,
1474 <a class="link" href="cairo-Paths.html#cairo-glyph-path" title="cairo_glyph_path ()"><code class="function">cairo_glyph_path()</code></a></p>
1475 </div>
1476 </div>
1477 <div class="footer">
1478 <hr>Generated by GTK-Doc V1.27</div>
1479 </body>
1480 </html>