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

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