docs/html/customizing-unicode-functions.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>Customizing Unicode functions: 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="buffers-language-script-and-direction.html" title="Buffers, language, script and direction">
   9 <link rel="prev" href="setting-buffer-properties.html" title="Setting buffer properties">
  10 <link rel="next" href="fonts-and-faces.html" title="Fonts, faces, and output">
  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"></td>
  17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  18 <td><a accesskey="u" href="buffers-language-script-and-direction.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="setting-buffer-properties.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="fonts-and-faces.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="section">
  23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  24 <a name="customizing-unicode-functions"></a>Customizing Unicode functions</h2></div></div></div>
  25 <p>
  26       HarfBuzz requires some simple functions for accessing
  27       information from the Unicode Character Database (such as the
  28       <code class="literal">General_Category</code> (gc) and
  29       <code class="literal">Script</code> (sc) properties) that is useful
  30       for shaping, as well as some useful operations like composing and
  31       decomposing code points.
  32     </p>
  33 <p>
  34       HarfBuzz includes its own internal, lightweight set of Unicode
  35       functions. At build time, it is also possible to compile support
  36       for some other options, such as the Unicode functions provided
  37       by GLib or the International Components for Unicode (ICU)
  38       library. Generally, this option is only of interest for client
  39       programs that have specific integration requirements or that do
  40       a significant amount of customization.
  41     </p>
  42 <p>
  43       If your program has access to other Unicode functions, however,
  44       such as through a system library or application framework, you
  45       might prefer to use those instead of the built-in
  46       options. HarfBuzz supports this by implementing its Unicode
  47       functions as a set of virtual methods that you can replace —
  48       without otherwise affecting HarfBuzz's functionality.
  49     </p>
  50 <p>
  51       The Unicode functions are specified in a structure called
  52       <code class="literal">unicode_funcs</code> which is attached to each
  53       buffer. But even though <code class="literal">unicode_funcs</code> is
  54       associated with a <span class="type">hb_buffer_t</span>, the functions
  55       themselves are called by other HarfBuzz APIs that access
  56       buffers, so it would be unwise for you to hook different
  57       functions into different buffers.
  58     </p>
  59 <p>
  60       In addition, you can mark your <code class="literal">unicode_funcs</code>
  61       as immutable by calling
  62       <code class="function">hb_unicode_funcs_make_immutable (ufuncs)</code>.
  63       This is especially useful if your code is a
  64       library or framework that will have its own client programs. By
  65       marking your Unicode function choices as immutable, you prevent
  66       your own client programs from changing the
  67       <code class="literal">unicode_funcs</code> configuration and introducing
  68       inconsistencies and errors downstream.
  69     </p>
  70 <p>
  71       You can retrieve the Unicode-functions configuration for
  72       your buffer by calling <code class="function">hb_buffer_get_unicode_funcs()</code>:
  73     </p>
  74 <pre class="programlisting">
  75       hb_unicode_funcs_t *ufunctions;
  76       ufunctions = hb_buffer_get_unicode_funcs(buf);
  77     </pre>
  78 <p>
  79       The current version of <code class="literal">unicode_funcs</code> uses six functions:
  80     </p>
  81 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  82 <li class="listitem"><p>
  83           <code class="function">hb_unicode_combining_class_func_t</code>:
  84           returns the Canonical Combining Class of a code point.
  85         </p></li>
  86 <li class="listitem"><p>
  87           <code class="function">hb_unicode_general_category_func_t</code>:
  88           returns the General Category (gc) of a code point.
  89         </p></li>
  90 <li class="listitem"><p>
  91           <code class="function">hb_unicode_mirroring_func_t</code>: returns
  92           the Mirroring Glyph code point (for bi-directional
  93           replacement) of a code point.
  94         </p></li>
  95 <li class="listitem"><p>
  96           <code class="function">hb_unicode_script_func_t</code>: returns the
  97           Script (sc) property of a code point.
  98         </p></li>
  99 <li class="listitem"><p>
 100           <code class="function">hb_unicode_compose_func_t</code>: returns the
 101           canonical composition of a sequence of two code points.
 102         </p></li>
 103 <li class="listitem"><p>
 104           <code class="function">hb_unicode_decompose_func_t</code>: returns
 105           the canonical decomposition of a code point.
 106         </p></li>
 107 </ul></div>
 108 <p>
 109       Note, however, that future HarfBuzz releases may alter this set.
 110     </p>
 111 <p>
 112       Each Unicode function has a corresponding setter, with which you
 113       can assign a callback to your replacement function. For example,
 114       to replace
 115       <code class="function">hb_unicode_general_category_func_t</code>, you can call
 116     </p>
 117 <pre class="programlisting">
 118       hb_unicode_funcs_set_general_category_func (*ufuncs, func, *user_data, destroy)
 119     </pre>
 120 <p>
 121       Virtualizing this set of Unicode functions is primarily intended
 122       to improve portability. There is no need for every client
 123       program to make the effort to replace the default options, so if
 124       you are unsure, do not feel any pressure to customize
 125       <code class="literal">unicode_funcs</code>.
 126     </p>
 127 </div>
 128 <div class="footer">
 129 <hr>Generated by GTK-Doc V1.32.1</div>
 130 </body>
 131 </html>