docs/html/setting-buffer-properties.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>Setting buffer properties: 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="adding-text-to-the-buffer.html" title="Adding text to the buffer">
  10 <link rel="next" href="customizing-unicode-functions.html" title="Customizing Unicode functions">
  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="adding-text-to-the-buffer.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="customizing-unicode-functions.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="setting-buffer-properties"></a>Setting buffer properties</h2></div></div></div>
  25 <p>
  26       Buffers containing input characters still need several
  27       properties set before HarfBuzz can shape their text correctly.
  28     </p>
  29 <p>
  30       Initially, all buffers are set to the
  31       <code class="literal">HB_BUFFER_CONTENT_TYPE_INVALID</code> content
  32       type. After adding text, the buffer should be set to
  33       <code class="literal">HB_BUFFER_CONTENT_TYPE_UNICODE</code> instead, which
  34       indicates that it contains un-shaped input
  35       characters. After shaping, the buffer will have the
  36       <code class="literal">HB_BUFFER_CONTENT_TYPE_GLYPHS</code> content type.
  37     </p>
  38 <p>
  39       <code class="function">hb_buffer_add_utf8()</code> and the
  40       other UTF functions set the content type of their buffer
  41       automatically. But if you are reusing a buffer you may want to
  42       check its state with
  43       <code class="function">hb_buffer_get_content_type(buffer)</code>. If
  44       necessary you can set the content type with
  45     </p>
  46 <pre class="programlisting">
  47       hb_buffer_set_content_type(buf, HB_BUFFER_CONTENT_TYPE_UNICODE);
  48     </pre>
  49 <p>
  50       to prepare for shaping.
  51     </p>
  52 <p>
  53       Buffers also need to carry information about the script,
  54       language, and text direction of their contents. You can set
  55       these properties individually:
  56     </p>
  57 <pre class="programlisting">
  58       hb_buffer_set_direction(buf, HB_DIRECTION_LTR);
  59       hb_buffer_set_script(buf, HB_SCRIPT_LATIN);
  60       hb_buffer_set_language(buf, hb_language_from_string("en", -1));
  61     </pre>
  62 <p>
  63       However, since these properties are often repeated for
  64       multiple text runs, you can also save them in a
  65       <code class="literal">hb_segment_properties_t</code> for reuse:
  66     </p>
  67 <pre class="programlisting">
  68       hb_segment_properties_t *savedprops;
  69       hb_buffer_get_segment_properties (buf, savedprops);
  70       ...
  71       hb_buffer_set_segment_properties (buf2, savedprops);
  72     </pre>
  73 <p>
  74       HarfBuzz also provides getter functions to retrieve a buffer's
  75       direction, script, and language properties individually.
  76     </p>
  77 <p>
  78       HarfBuzz recognizes four text directions in
  79       <span class="type">hb_direction_t</span>: left-to-right
  80       (<code class="literal">HB_DIRECTION_LTR</code>), right-to-left (<code class="literal">HB_DIRECTION_RTL</code>),
  81       top-to-bottom (<code class="literal">HB_DIRECTION_TTB</code>), and
  82       bottom-to-top (<code class="literal">HB_DIRECTION_BTT</code>).  For the
  83       script property, HarfBuzz uses identifiers based on the
  84       <a class="ulink" href="https://unicode.org/iso15924/" target="_top">ISO 15924
  85       standard</a>. For languages, HarfBuzz uses tags based on the
  86       <a class="ulink" href="https://tools.ietf.org/html/bcp47" target="_top">IETF BCP 47</a> standard.
  87     </p>
  88 <p>
  89       Helper functions are provided to convert character strings into
  90       the necessary script and language tag types.
  91     </p>
  92 <p>
  93       Two additional buffer properties to be aware of are the
  94       "invisible glyph" and the replacement code point. The
  95       replacement code point is inserted into buffer output in place of
  96       any invalid code points encountered in the input. By default, it
  97       is the Unicode <code class="literal">REPLACEMENT CHARACTER</code> code
  98       point, <code class="literal">U+FFFD</code> "�". You can change this with
  99     </p>
 100 <pre class="programlisting">
 101       hb_buffer_set_replacement_codepoint(buf, replacement);
 102     </pre>
 103 <p>
 104       passing in the replacement Unicode code point as the
 105       <em class="parameter"><code>replacement</code></em> parameter.
 106     </p>
 107 <p>
 108       The invisible glyph is used to replace all output glyphs that
 109       are invisible. By default, the standard space character
 110       <code class="literal">U+0020</code> is used; you can replace this (for
 111       example, when using a font that provides script-specific
 112       spaces) with
 113     </p>
 114 <pre class="programlisting">
 115       hb_buffer_set_invisible_glyph(buf, replacement_glyph);
 116     </pre>
 117 <p>
 118       Do note that in the <em class="parameter"><code>replacement_glyph</code></em>
 119       parameter, you must provide the glyph ID of the replacement you
 120       wish to use, not the Unicode code point.
 121     </p>
 122 <p>
 123       HarfBuzz supports a few additional flags you might want to set
 124       on your buffer under certain circumstances. The
 125       <code class="literal">HB_BUFFER_FLAG_BOT</code> and
 126       <code class="literal">HB_BUFFER_FLAG_EOT</code> flags tell HarfBuzz
 127       that the buffer represents the beginning or end (respectively)
 128       of a text element (such as a paragraph or other block). Knowing
 129       this allows HarfBuzz to apply certain contextual font features
 130       when shaping, such as initial or final variants in connected
 131       scripts.
 132     </p>
 133 <p>
 134       <code class="literal">HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES</code>
 135       tells HarfBuzz not to hide glyphs with the
 136       <code class="literal">Default_Ignorable</code> property in Unicode. This
 137       property designates control characters and other non-printing
 138       code points, such as joiners and variation selectors. Normally
 139       HarfBuzz replaces them in the output buffer with zero-width
 140       space glyphs (using the "invisible glyph" property discussed
 141       above); setting this flag causes them to be printed, which can
 142       be helpful for troubleshooting.
 143     </p>
 144 <p>
 145       Conversely, setting the
 146       <code class="literal">HB_BUFFER_FLAG_REMOVE_DEFAULT_IGNORABLES</code> flag
 147       tells HarfBuzz to remove <code class="literal">Default_Ignorable</code>
 148       glyphs from the output buffer entirely. Finally, setting the
 149       <code class="literal">HB_BUFFER_FLAG_DO_NOT_INSERT_DOTTED_CIRCLE</code>
 150       flag tells HarfBuzz not to insert the dotted-circle glyph
 151       (<code class="literal">U+25CC</code>, "◌"), which is normally
 152       inserted into buffer output when broken character sequences are
 153       encountered (such as combining marks that are not attached to a
 154       base character).
 155     </p>
 156 </div>
 157 <div class="footer">
 158 <hr>Generated by GTK-Doc V1.32.1</div>
 159 </body>
 160 </html>