docs/html/harfbuzz-hb-ot-name.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>hb-ot-name: HarfBuzz Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
   7 <link rel="home" href="index.html" title="HarfBuzz Manual">
   8 <link rel="up" href="ch13.html" title="OpenType API">
   9 <link rel="prev" href="harfbuzz-hb-ot-math.html" title="hb-ot-math">
  10 <link rel="next" href="harfbuzz-hb-ot-shape.html" title="hb-ot-shape">
  11 <meta name="generator" content="GTK-Doc V1.32.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts">
  17 <a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span>
  18                   <a href="#harfbuzz-hb-ot-name.description" class="shortcut">Description</a></span>
  19 </td>
  20 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  21 <td><a accesskey="u" href="ch13.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  22 <td><a accesskey="p" href="harfbuzz-hb-ot-math.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  23 <td><a accesskey="n" href="harfbuzz-hb-ot-shape.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  24 </tr></table>
  25 <div class="refentry">
  26 <a name="harfbuzz-hb-ot-name"></a><div class="titlepage"></div>
  27 <div class="refnamediv"><table width="100%"><tr>
  28 <td valign="top">
  29 <h2><span class="refentrytitle"><a name="harfbuzz-hb-ot-name.top_of_page"></a>hb-ot-name</span></h2>
  30 <p>hb-ot-name — OpenType font name information</p>
  31 </td>
  32 <td class="gallery_image" valign="top" align="right"></td>
  33 </tr></table></div>
  34 <div class="refsect1">
  35 <a name="harfbuzz-hb-ot-name.functions"></a><h2>Functions</h2>
  36 <div class="informaltable"><table class="informaltable" width="100%" border="0">
  37 <colgroup>
  38 <col width="150px" class="functions_proto_type">
  39 <col class="functions_proto_name">
  40 </colgroup>
  41 <tbody>
  42 <tr>
  43 <td class="function_type">const <span class="returnvalue">hb_ot_name_entry_t</span> *
  44 </td>
  45 <td class="function_name">
  46 <a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-list-names" title="hb_ot_name_list_names ()">hb_ot_name_list_names</a> <span class="c_punctuation">()</span>
  47 </td>
  48 </tr>
  49 <tr>
  50 <td class="function_type">unsigned <span class="returnvalue">int</span>
  51 </td>
  52 <td class="function_name">
  53 <a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-get-utf16" title="hb_ot_name_get_utf16 ()">hb_ot_name_get_utf16</a> <span class="c_punctuation">()</span>
  54 </td>
  55 </tr>
  56 <tr>
  57 <td class="function_type">unsigned <span class="returnvalue">int</span>
  58 </td>
  59 <td class="function_name">
  60 <a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-get-utf32" title="hb_ot_name_get_utf32 ()">hb_ot_name_get_utf32</a> <span class="c_punctuation">()</span>
  61 </td>
  62 </tr>
  63 <tr>
  64 <td class="function_type">unsigned <span class="returnvalue">int</span>
  65 </td>
  66 <td class="function_name">
  67 <a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-get-utf8" title="hb_ot_name_get_utf8 ()">hb_ot_name_get_utf8</a> <span class="c_punctuation">()</span>
  68 </td>
  69 </tr>
  70 </tbody>
  71 </table></div>
  72 </div>
  73 <div class="refsect1">
  74 <a name="harfbuzz-hb-ot-name.other"></a><h2>Types and Values</h2>
  75 <div class="informaltable"><table class="informaltable" width="100%" border="0">
  76 <colgroup>
  77 <col width="150px" class="other_proto_type">
  78 <col class="other_proto_name">
  79 </colgroup>
  80 <tbody><tr>
  81 <td class="typedef_keyword">typedef</td>
  82 <td class="function_name"><a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-id-t" title="hb_ot_name_id_t">hb_ot_name_id_t</a></td>
  83 </tr></tbody>
  84 </table></div>
  85 </div>
  86 <div class="refsect1">
  87 <a name="harfbuzz-hb-ot-name.includes"></a><h2>Includes</h2>
  88 <pre class="synopsis">#include &lt;hb-ot.h&gt;
  89 </pre>
  90 </div>
  91 <div class="refsect1">
  92 <a name="harfbuzz-hb-ot-name.description"></a><h2>Description</h2>
  93 <p>Functions for fetching name strings from OpenType fonts.</p>
  94 </div>
  95 <div class="refsect1">
  96 <a name="harfbuzz-hb-ot-name.functions_details"></a><h2>Functions</h2>
  97 <div class="refsect2">
  98 <a name="hb-ot-name-list-names"></a><h3>hb_ot_name_list_names ()</h3>
  99 <pre class="programlisting">const <span class="returnvalue">hb_ot_name_entry_t</span> *
 100 hb_ot_name_list_names (<em class="parameter"><code><a class="link" href="harfbuzz-hb-face.html#hb-face-t" title="hb_face_t"><span class="type">hb_face_t</span></a> *face</code></em>,
 101                        <em class="parameter"><code>unsigned <span class="type">int</span> *num_entries</code></em>);</pre>
 102 <p>Enumerates all available name IDs and language combinations. Returned
 103 array is owned by the <em class="parameter"><code>face</code></em>
 104  and should not be modified.  It can be
 105 used as long as <em class="parameter"><code>face</code></em>
 106  is alive.</p>
 107 <div class="refsect3">
 108 <a name="hb-ot-name-list-names.parameters"></a><h4>Parameters</h4>
 109 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 110 <colgroup>
 111 <col width="150px" class="parameters_name">
 112 <col class="parameters_description">
 113 <col width="200px" class="parameters_annotations">
 114 </colgroup>
 115 <tbody>
 116 <tr>
 117 <td class="parameter_name"><p>face</p></td>
 118 <td class="parameter_description"><p>font face.</p></td>
 119 <td class="parameter_annotations"> </td>
 120 </tr>
 121 <tr>
 122 <td class="parameter_name"><p>num_entries</p></td>
 123 <td class="parameter_description"><p>number of returned entries. </p></td>
 124 <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
 125 </tr>
 126 </tbody>
 127 </table></div>
 128 </div>
 129 <div class="refsect3">
 130 <a name="hb-ot-name-list-names.returns"></a><h4>Returns</h4>
 131 <p>Array of available name entries. </p>
 132 <p><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=num_entries]</span></p>
 133 </div>
 134 <p class="since">Since: <a class="link" href="api-index-2-1-0.html#api-index-2.1.0">2.1.0</a></p>
 135 </div>
 136 <hr>
 137 <div class="refsect2">
 138 <a name="hb-ot-name-get-utf16"></a><h3>hb_ot_name_get_utf16 ()</h3>
 139 <pre class="programlisting">unsigned <span class="returnvalue">int</span>
 140 hb_ot_name_get_utf16 (<em class="parameter"><code><a class="link" href="harfbuzz-hb-face.html#hb-face-t" title="hb_face_t"><span class="type">hb_face_t</span></a> *face</code></em>,
 141                       <em class="parameter"><code><a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-id-t" title="hb_ot_name_id_t"><span class="type">hb_ot_name_id_t</span></a> name_id</code></em>,
 142                       <em class="parameter"><code><a class="link" href="harfbuzz-hb-common.html#hb-language-t" title="hb_language_t"><span class="type">hb_language_t</span></a> language</code></em>,
 143                       <em class="parameter"><code>unsigned <span class="type">int</span> *text_size</code></em>,
 144                       <em class="parameter"><code><span class="type">uint16_t</span> *text</code></em>);</pre>
 145 <p>Fetches a font name from the OpenType 'name' table.
 146 If <em class="parameter"><code>language</code></em>
 147  is <a class="link" href="harfbuzz-hb-common.html#HB-LANGUAGE-INVALID:CAPS" title="HB_LANGUAGE_INVALID"><span class="type">HB_LANGUAGE_INVALID</span></a>, English ("en") is assumed.
 148 Returns string in UTF-16 encoding.</p>
 149 <div class="refsect3">
 150 <a name="hb-ot-name-get-utf16.parameters"></a><h4>Parameters</h4>
 151 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 152 <colgroup>
 153 <col width="150px" class="parameters_name">
 154 <col class="parameters_description">
 155 <col width="200px" class="parameters_annotations">
 156 </colgroup>
 157 <tbody>
 158 <tr>
 159 <td class="parameter_name"><p>face</p></td>
 160 <td class="parameter_description"><p>font face.</p></td>
 161 <td class="parameter_annotations"> </td>
 162 </tr>
 163 <tr>
 164 <td class="parameter_name"><p>name_id</p></td>
 165 <td class="parameter_description"><p>OpenType name identifier to fetch.</p></td>
 166 <td class="parameter_annotations"> </td>
 167 </tr>
 168 <tr>
 169 <td class="parameter_name"><p>language</p></td>
 170 <td class="parameter_description"><p>language to fetch the name for.</p></td>
 171 <td class="parameter_annotations"> </td>
 172 </tr>
 173 <tr>
 174 <td class="parameter_name"><p>text_size</p></td>
 175 <td class="parameter_description"><p>input size of <em class="parameter"><code>text</code></em>
 176 buffer, and output size of
 177 text written to buffer. </p></td>
 178 <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
 179 </tr>
 180 <tr>
 181 <td class="parameter_name"><p>text</p></td>
 182 <td class="parameter_description"><p>buffer to write fetched name into. </p></td>
 183 <td class="parameter_annotations"><span class="annotation">[<acronym title="Out parameter, where caller must allocate storage."><span class="acronym">out caller-allocates</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=text_size]</span></td>
 184 </tr>
 185 </tbody>
 186 </table></div>
 187 </div>
 188 <div class="refsect3">
 189 <a name="hb-ot-name-get-utf16.returns"></a><h4>Returns</h4>
 190 <p> full length of the requested string, or 0 if not found.</p>
 191 </div>
 192 <p class="since">Since: <a class="link" href="api-index-2-1-0.html#api-index-2.1.0">2.1.0</a></p>
 193 </div>
 194 <hr>
 195 <div class="refsect2">
 196 <a name="hb-ot-name-get-utf32"></a><h3>hb_ot_name_get_utf32 ()</h3>
 197 <pre class="programlisting">unsigned <span class="returnvalue">int</span>
 198 hb_ot_name_get_utf32 (<em class="parameter"><code><a class="link" href="harfbuzz-hb-face.html#hb-face-t" title="hb_face_t"><span class="type">hb_face_t</span></a> *face</code></em>,
 199                       <em class="parameter"><code><a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-id-t" title="hb_ot_name_id_t"><span class="type">hb_ot_name_id_t</span></a> name_id</code></em>,
 200                       <em class="parameter"><code><a class="link" href="harfbuzz-hb-common.html#hb-language-t" title="hb_language_t"><span class="type">hb_language_t</span></a> language</code></em>,
 201                       <em class="parameter"><code>unsigned <span class="type">int</span> *text_size</code></em>,
 202                       <em class="parameter"><code><span class="type">uint32_t</span> *text</code></em>);</pre>
 203 <p>Fetches a font name from the OpenType 'name' table.
 204 If <em class="parameter"><code>language</code></em>
 205  is <a class="link" href="harfbuzz-hb-common.html#HB-LANGUAGE-INVALID:CAPS" title="HB_LANGUAGE_INVALID"><span class="type">HB_LANGUAGE_INVALID</span></a>, English ("en") is assumed.
 206 Returns string in UTF-32 encoding.</p>
 207 <div class="refsect3">
 208 <a name="hb-ot-name-get-utf32.parameters"></a><h4>Parameters</h4>
 209 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 210 <colgroup>
 211 <col width="150px" class="parameters_name">
 212 <col class="parameters_description">
 213 <col width="200px" class="parameters_annotations">
 214 </colgroup>
 215 <tbody>
 216 <tr>
 217 <td class="parameter_name"><p>face</p></td>
 218 <td class="parameter_description"><p>font face.</p></td>
 219 <td class="parameter_annotations"> </td>
 220 </tr>
 221 <tr>
 222 <td class="parameter_name"><p>name_id</p></td>
 223 <td class="parameter_description"><p>OpenType name identifier to fetch.</p></td>
 224 <td class="parameter_annotations"> </td>
 225 </tr>
 226 <tr>
 227 <td class="parameter_name"><p>language</p></td>
 228 <td class="parameter_description"><p>language to fetch the name for.</p></td>
 229 <td class="parameter_annotations"> </td>
 230 </tr>
 231 <tr>
 232 <td class="parameter_name"><p>text_size</p></td>
 233 <td class="parameter_description"><p>input size of <em class="parameter"><code>text</code></em>
 234 buffer, and output size of
 235 text written to buffer. </p></td>
 236 <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
 237 </tr>
 238 <tr>
 239 <td class="parameter_name"><p>text</p></td>
 240 <td class="parameter_description"><p>buffer to write fetched name into. </p></td>
 241 <td class="parameter_annotations"><span class="annotation">[<acronym title="Out parameter, where caller must allocate storage."><span class="acronym">out caller-allocates</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=text_size]</span></td>
 242 </tr>
 243 </tbody>
 244 </table></div>
 245 </div>
 246 <div class="refsect3">
 247 <a name="hb-ot-name-get-utf32.returns"></a><h4>Returns</h4>
 248 <p> full length of the requested string, or 0 if not found.</p>
 249 </div>
 250 <p class="since">Since: <a class="link" href="api-index-2-1-0.html#api-index-2.1.0">2.1.0</a></p>
 251 </div>
 252 <hr>
 253 <div class="refsect2">
 254 <a name="hb-ot-name-get-utf8"></a><h3>hb_ot_name_get_utf8 ()</h3>
 255 <pre class="programlisting">unsigned <span class="returnvalue">int</span>
 256 hb_ot_name_get_utf8 (<em class="parameter"><code><a class="link" href="harfbuzz-hb-face.html#hb-face-t" title="hb_face_t"><span class="type">hb_face_t</span></a> *face</code></em>,
 257                      <em class="parameter"><code><a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-id-t" title="hb_ot_name_id_t"><span class="type">hb_ot_name_id_t</span></a> name_id</code></em>,
 258                      <em class="parameter"><code><a class="link" href="harfbuzz-hb-common.html#hb-language-t" title="hb_language_t"><span class="type">hb_language_t</span></a> language</code></em>,
 259                      <em class="parameter"><code>unsigned <span class="type">int</span> *text_size</code></em>,
 260                      <em class="parameter"><code><span class="type">char</span> *text</code></em>);</pre>
 261 <p>Fetches a font name from the OpenType 'name' table.
 262 If <em class="parameter"><code>language</code></em>
 263  is <a class="link" href="harfbuzz-hb-common.html#HB-LANGUAGE-INVALID:CAPS" title="HB_LANGUAGE_INVALID"><span class="type">HB_LANGUAGE_INVALID</span></a>, English ("en") is assumed.
 264 Returns string in UTF-8 encoding.</p>
 265 <div class="refsect3">
 266 <a name="hb-ot-name-get-utf8.parameters"></a><h4>Parameters</h4>
 267 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 268 <colgroup>
 269 <col width="150px" class="parameters_name">
 270 <col class="parameters_description">
 271 <col width="200px" class="parameters_annotations">
 272 </colgroup>
 273 <tbody>
 274 <tr>
 275 <td class="parameter_name"><p>face</p></td>
 276 <td class="parameter_description"><p>font face.</p></td>
 277 <td class="parameter_annotations"> </td>
 278 </tr>
 279 <tr>
 280 <td class="parameter_name"><p>name_id</p></td>
 281 <td class="parameter_description"><p>OpenType name identifier to fetch.</p></td>
 282 <td class="parameter_annotations"> </td>
 283 </tr>
 284 <tr>
 285 <td class="parameter_name"><p>language</p></td>
 286 <td class="parameter_description"><p>language to fetch the name for.</p></td>
 287 <td class="parameter_annotations"> </td>
 288 </tr>
 289 <tr>
 290 <td class="parameter_name"><p>text_size</p></td>
 291 <td class="parameter_description"><p>input size of <em class="parameter"><code>text</code></em>
 292 buffer, and output size of
 293 text written to buffer. </p></td>
 294 <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
 295 </tr>
 296 <tr>
 297 <td class="parameter_name"><p>text</p></td>
 298 <td class="parameter_description"><p>buffer to write fetched name into. </p></td>
 299 <td class="parameter_annotations"><span class="annotation">[<acronym title="Out parameter, where caller must allocate storage."><span class="acronym">out caller-allocates</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=text_size]</span></td>
 300 </tr>
 301 </tbody>
 302 </table></div>
 303 </div>
 304 <div class="refsect3">
 305 <a name="hb-ot-name-get-utf8.returns"></a><h4>Returns</h4>
 306 <p> full length of the requested string, or 0 if not found.</p>
 307 </div>
 308 <p class="since">Since: <a class="link" href="api-index-2-1-0.html#api-index-2.1.0">2.1.0</a></p>
 309 </div>
 310 </div>
 311 <div class="refsect1">
 312 <a name="harfbuzz-hb-ot-name.other_details"></a><h2>Types and Values</h2>
 313 <div class="refsect2">
 314 <a name="hb-ot-name-id-t"></a><h3>hb_ot_name_id_t</h3>
 315 <pre class="programlisting">typedef unsigned int hb_ot_name_id_t;
 316 </pre>
 317 <p>An integral type representing an OpenType 'name' table name identifier.
 318 There are predefined name IDs, as well as name IDs return from other
 319 API.  These can be used to fetch name strings from a font face.</p>
 320 <p class="since">Since: <a class="link" href="api-index-2-0-0.html#api-index-2.0.0">2.0.0</a></p>
 321 </div>
 322 </div>
 323 </div>
 324 <div class="footer">
 325 <hr>Generated by GTK-Doc V1.32.1</div>
 326 </body>
 327 </html>