docs/xml/bidi.xml

   1 <refentry id="pango-Bidirectional-Text">
   2 <refmeta>
   3 <refentrytitle role="top_of_page" id="pango-Bidirectional-Text.top_of_page">Bidirectional Text</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>PANGO Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Bidirectional Text</refname>
  10 <refpurpose>Types and functions to help with handling bidirectional text</refpurpose>
  11 </refnamediv>
  12
  13 <refsynopsisdiv id="pango-Bidirectional-Text.synopsis" role="synopsis">
  14 <title role="synopsis.title">Synopsis</title>
  15
  16 <synopsis>
  17 enum                <link linkend="PangoDirection">PangoDirection</link>;
  18 <link linkend="PangoDirection">PangoDirection</link>      <link linkend="pango-unichar-direction">pango_unichar_direction</link>             (<link linkend="gunichar">gunichar</link> ch);
  19 <link linkend="PangoDirection">PangoDirection</link>      <link linkend="pango-find-base-dir">pango_find_base_dir</link>                 (const <link linkend="gchar">gchar</link> *text,
  20                                                          <link linkend="gint">gint</link> length);
  21 <link linkend="gboolean">gboolean</link>            <link linkend="pango-get-mirror-char">pango_get_mirror_char</link>               (<link linkend="gunichar">gunichar</link> ch,
  22                                                          <link linkend="gunichar">gunichar</link> *mirrored_ch);
  23 enum                <link linkend="PangoBidiType">PangoBidiType</link>;
  24 <link linkend="PangoBidiType">PangoBidiType</link>       <link linkend="pango-bidi-type-for-unichar">pango_bidi_type_for_unichar</link>         (<link linkend="gunichar">gunichar</link> ch);
  25 </synopsis>
  26 </refsynopsisdiv>
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36 <refsect1 id="pango-Bidirectional-Text.description" role="desc">
  37 <title role="desc.title">Description</title>
  38 <para>
  39 Pango supports bidirectional text (like Arabic and Hebrew) automatically.
  40 Some applications however, need some help to correctly handle bidirectional
  41 text.
  42 </para>
  43 <para>
  44 The <link linkend="PangoDirection"><type>PangoDirection</type></link> type can be used with <link linkend="pango-context-set-base-dir"><function>pango_context_set_base_dir()</function></link> to
  45 instruct Pango about direction of text, though in most cases Pango detects
  46 that correctly and automatically.  The rest of the facilities in this section
  47 are used internally by Pango already, and are provided to help applications
  48 that need more direct control over bidirectional setting of text.
  49 </para>
  50 </refsect1>
  51
  52 <refsect1 id="pango-Bidirectional-Text.details" role="details">
  53 <title role="details.title">Details</title>
  54 <refsect2 id="PangoDirection" role="enum">
  55 <title>enum PangoDirection</title>
  56 <indexterm zone="PangoDirection"><primary sortas="PangoDirection">PangoDirection</primary></indexterm><programlisting>typedef enum {
  57   PANGO_DIRECTION_LTR,
  58   PANGO_DIRECTION_RTL,
  59   PANGO_DIRECTION_TTB_LTR,
  60   PANGO_DIRECTION_TTB_RTL,
  61   PANGO_DIRECTION_WEAK_LTR,
  62   PANGO_DIRECTION_WEAK_RTL,
  63   PANGO_DIRECTION_NEUTRAL
  64 } PangoDirection;
  65 </programlisting>
  66 <para>
  67 The <link linkend="PangoDirection"><type>PangoDirection</type></link> type represents a direction in the
  68 Unicode bidirectional algorithm; not every value in this
  69 enumeration makes sense for every usage of <link linkend="PangoDirection"><type>PangoDirection</type></link>;
  70 for example, the return value of <link linkend="pango-unichar-direction"><function>pango_unichar_direction()</function></link>
  71 and <link linkend="pango-find-base-dir"><function>pango_find_base_dir()</function></link> cannot be <link linkend="PANGO-DIRECTION-WEAK-LTR--CAPS"><literal>PANGO_DIRECTION_WEAK_LTR</literal></link>
  72 or <link linkend="PANGO-DIRECTION-WEAK-RTL--CAPS"><literal>PANGO_DIRECTION_WEAK_RTL</literal></link>, since every character is either
  73 neutral or has a strong direction; on the other hand
  74 <link linkend="PANGO-DIRECTION-NEUTRAL--CAPS"><literal>PANGO_DIRECTION_NEUTRAL</literal></link> doesn't make sense to pass
  75 to <link linkend="pango-itemize-with-base-dir"><function>pango_itemize_with_base_dir()</function></link>.
  76 </para>
  77 <para>
  78 The <link linkend="PANGO-DIRECTION-TTB-LTR--CAPS"><literal>PANGO_DIRECTION_TTB_LTR</literal></link>, <link linkend="PANGO-DIRECTION-TTB-RTL--CAPS"><literal>PANGO_DIRECTION_TTB_RTL</literal></link>
  79 values come from an earlier interpretation of this
  80 enumeration as the writing direction of a block of
  81 text and are no longer used; See <link linkend="PangoGravity"><type>PangoGravity</type></link> for how
  82 vertical text is handled in Pango.</para>
  83 <para>
  84 </para><variablelist role="enum">
  85 <varlistentry id="PANGO-DIRECTION-LTR--CAPS" role="constant">
  86 <term><literal>PANGO_DIRECTION_LTR</literal></term>
  87 <listitem><simpara> A strong left-to-right direction
  88 </simpara></listitem>
  89 </varlistentry>
  90 <varlistentry id="PANGO-DIRECTION-RTL--CAPS" role="constant">
  91 <term><literal>PANGO_DIRECTION_RTL</literal></term>
  92 <listitem><simpara> A strong right-to-left direction
  93 </simpara></listitem>
  94 </varlistentry>
  95 <varlistentry id="PANGO-DIRECTION-TTB-LTR--CAPS" role="constant">
  96 <term><literal>PANGO_DIRECTION_TTB_LTR</literal></term>
  97 <listitem><simpara> Deprecated value; treated the
  98   same as <link linkend="PANGO-DIRECTION-RTL--CAPS"><literal>PANGO_DIRECTION_RTL</literal></link>.
  99 </simpara></listitem>
 100 </varlistentry>
 101 <varlistentry id="PANGO-DIRECTION-TTB-RTL--CAPS" role="constant">
 102 <term><literal>PANGO_DIRECTION_TTB_RTL</literal></term>
 103 <listitem><simpara> Deprecated value; treated the
 104   same as <link linkend="PANGO-DIRECTION-LTR--CAPS"><literal>PANGO_DIRECTION_LTR</literal></link>
 105 </simpara></listitem>
 106 </varlistentry>
 107 <varlistentry id="PANGO-DIRECTION-WEAK-LTR--CAPS" role="constant">
 108 <term><literal>PANGO_DIRECTION_WEAK_LTR</literal></term>
 109 <listitem><simpara> A weak left-to-right direction
 110 </simpara></listitem>
 111 </varlistentry>
 112 <varlistentry id="PANGO-DIRECTION-WEAK-RTL--CAPS" role="constant">
 113 <term><literal>PANGO_DIRECTION_WEAK_RTL</literal></term>
 114 <listitem><simpara> A weak right-to-left direction
 115 </simpara></listitem>
 116 </varlistentry>
 117 <varlistentry id="PANGO-DIRECTION-NEUTRAL--CAPS" role="constant">
 118 <term><literal>PANGO_DIRECTION_NEUTRAL</literal></term>
 119 <listitem><simpara> No direction specified
 120 </simpara></listitem>
 121 </varlistentry>
 122 </variablelist></refsect2>
 123 <refsect2 id="pango-unichar-direction" role="function">
 124 <title>pango_unichar_direction ()</title>
 125 <indexterm zone="pango-unichar-direction"><primary sortas="pango_unichar_direction">pango_unichar_direction</primary></indexterm><programlisting><link linkend="PangoDirection">PangoDirection</link>      pango_unichar_direction             (<link linkend="gunichar">gunichar</link> ch);</programlisting>
 126 <para>
 127 Determines the inherent direction of a character; either
 128 <link linkend="PANGO-DIRECTION-LTR--CAPS"><literal>PANGO_DIRECTION_LTR</literal></link>, <link linkend="PANGO-DIRECTION-RTL--CAPS"><literal>PANGO_DIRECTION_RTL</literal></link>, or
 129 <link linkend="PANGO-DIRECTION-NEUTRAL--CAPS"><literal>PANGO_DIRECTION_NEUTRAL</literal></link>.
 130 </para>
 131 <para>
 132 This function is useful to categorize characters into left-to-right
 133 letters, right-to-left letters, and everything else.  If full
 134 Unicode bidirectional type of a character is needed,
 135 <link linkend="pango-bidi-type-for-gunichar"><function>pango_bidi_type_for_gunichar()</function></link> can be used instead.</para>
 136 <para>
 137 </para><variablelist role="params">
 138 <varlistentry><term><parameter>ch</parameter>&#160;:</term>
 139 <listitem><simpara> a Unicode character
 140 </simpara></listitem></varlistentry>
 141 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the direction of the character.
 142 </simpara></listitem></varlistentry>
 143 </variablelist></refsect2>
 144 <refsect2 id="pango-find-base-dir" role="function" condition="since:1.4">
 145 <title>pango_find_base_dir ()</title>
 146 <indexterm zone="pango-find-base-dir" role="1.4"><primary sortas="pango_find_base_dir">pango_find_base_dir</primary></indexterm><programlisting><link linkend="PangoDirection">PangoDirection</link>      pango_find_base_dir                 (const <link linkend="gchar">gchar</link> *text,
 147                                                          <link linkend="gint">gint</link> length);</programlisting>
 148 <para>
 149 Searches a string the first character that has a strong
 150 direction, according to the Unicode bidirectional algorithm.</para>
 151 <para>
 152 </para><variablelist role="params">
 153 <varlistentry><term><parameter>text</parameter>&#160;:</term>
 154 <listitem><simpara>   the text to process
 155 </simpara></listitem></varlistentry>
 156 <varlistentry><term><parameter>length</parameter>&#160;:</term>
 157 <listitem><simpara> length of <parameter>text</parameter> in bytes (may be -1 if <parameter>text</parameter> is nul-terminated)
 158 </simpara></listitem></varlistentry>
 159 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The direction corresponding to the first strong character.
 160 If no such character is found, then <link linkend="PANGO-DIRECTION-NEUTRAL--CAPS"><literal>PANGO_DIRECTION_NEUTRAL</literal></link> is returned.
 161
 162 </simpara></listitem></varlistentry>
 163 </variablelist><para role="since">Since 1.4</para></refsect2>
 164 <refsect2 id="pango-get-mirror-char" role="function" condition="deprecated:">
 165 <title>pango_get_mirror_char ()</title>
 166 <indexterm zone="pango-get-mirror-char" role="deprecated"><primary sortas="pango_get_mirror_char">pango_get_mirror_char</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_get_mirror_char               (<link linkend="gunichar">gunichar</link> ch,
 167                                                          <link linkend="gunichar">gunichar</link> *mirrored_ch);</programlisting>
 168 <warning><para><literal>pango_get_mirror_char</literal> is deprecated and should not be used in newly-written code.</para></warning>
 169 <para>
 170 If <parameter>ch</parameter> has the Unicode mirrored property and there is another Unicode
 171 character that typically has a glyph that is the mirror image of <parameter>ch</parameter>'s
 172 glyph, puts that character in the address pointed to by <parameter>mirrored_ch</parameter>.
 173 </para>
 174 <para>
 175 Use <link linkend="g-unichar-get-mirror-char"><function>g_unichar_get_mirror_char()</function></link> instead; the docs for that function
 176 provide full details.</para>
 177 <para>
 178 </para><variablelist role="params">
 179 <varlistentry><term><parameter>ch</parameter>&#160;:</term>
 180 <listitem><simpara> a Unicode character
 181 </simpara></listitem></varlistentry>
 182 <varlistentry><term><parameter>mirrored_ch</parameter>&#160;:</term>
 183 <listitem><simpara> location to store the mirrored character
 184 </simpara></listitem></varlistentry>
 185 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>ch</parameter> has a mirrored character and <parameter>mirrored_ch</parameter> is
 186 filled in, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise
 187 </simpara></listitem></varlistentry>
 188 </variablelist></refsect2>
 189 <refsect2 id="PangoBidiType" role="enum" condition="since:1.22">
 190 <title>enum PangoBidiType</title>
 191 <indexterm zone="PangoBidiType" role="1.22"><primary sortas="PangoBidiType">PangoBidiType</primary></indexterm><programlisting>typedef enum {
 192   /* Strong types */
 193   PANGO_BIDI_TYPE_L,
 194   PANGO_BIDI_TYPE_LRE,
 195   PANGO_BIDI_TYPE_LRO,
 196   PANGO_BIDI_TYPE_R,
 197   PANGO_BIDI_TYPE_AL,
 198   PANGO_BIDI_TYPE_RLE,
 199   PANGO_BIDI_TYPE_RLO,
 200
 201   /* Weak types */
 202   PANGO_BIDI_TYPE_PDF,
 203   PANGO_BIDI_TYPE_EN,
 204   PANGO_BIDI_TYPE_ES,
 205   PANGO_BIDI_TYPE_ET,
 206   PANGO_BIDI_TYPE_AN,
 207   PANGO_BIDI_TYPE_CS,
 208   PANGO_BIDI_TYPE_NSM,
 209   PANGO_BIDI_TYPE_BN,
 210
 211   /* Neutral types */
 212   PANGO_BIDI_TYPE_B,
 213   PANGO_BIDI_TYPE_S,
 214   PANGO_BIDI_TYPE_WS,
 215   PANGO_BIDI_TYPE_ON
 216 } PangoBidiType;
 217 </programlisting>
 218 <para>
 219 The <link linkend="PangoBidiType"><type>PangoBidiType</type></link> type represents the bidirectional character
 220 type of a Unicode character as specified by the
 221 <ulink url="http://www.unicode.org/reports/tr9/">Unicode bidirectional algorithm</ulink>.</para>
 222 <para>
 223 </para><variablelist role="enum">
 224 <varlistentry id="PANGO-BIDI-TYPE-L--CAPS" role="constant">
 225 <term><literal>PANGO_BIDI_TYPE_L</literal></term>
 226 <listitem><simpara> Left-to-Right
 227 </simpara></listitem>
 228 </varlistentry>
 229 <varlistentry id="PANGO-BIDI-TYPE-LRE--CAPS" role="constant">
 230 <term><literal>PANGO_BIDI_TYPE_LRE</literal></term>
 231 <listitem><simpara> Left-to-Right Embedding
 232 </simpara></listitem>
 233 </varlistentry>
 234 <varlistentry id="PANGO-BIDI-TYPE-LRO--CAPS" role="constant">
 235 <term><literal>PANGO_BIDI_TYPE_LRO</literal></term>
 236 <listitem><simpara> Left-to-Right Override
 237 </simpara></listitem>
 238 </varlistentry>
 239 <varlistentry id="PANGO-BIDI-TYPE-R--CAPS" role="constant">
 240 <term><literal>PANGO_BIDI_TYPE_R</literal></term>
 241 <listitem><simpara> Right-to-Left
 242 </simpara></listitem>
 243 </varlistentry>
 244 <varlistentry id="PANGO-BIDI-TYPE-AL--CAPS" role="constant">
 245 <term><literal>PANGO_BIDI_TYPE_AL</literal></term>
 246 <listitem><simpara> Right-to-Left Arabic
 247 </simpara></listitem>
 248 </varlistentry>
 249 <varlistentry id="PANGO-BIDI-TYPE-RLE--CAPS" role="constant">
 250 <term><literal>PANGO_BIDI_TYPE_RLE</literal></term>
 251 <listitem><simpara> Right-to-Left Embedding
 252 </simpara></listitem>
 253 </varlistentry>
 254 <varlistentry id="PANGO-BIDI-TYPE-RLO--CAPS" role="constant">
 255 <term><literal>PANGO_BIDI_TYPE_RLO</literal></term>
 256 <listitem><simpara> Right-to-Left Override
 257 </simpara></listitem>
 258 </varlistentry>
 259 <varlistentry id="PANGO-BIDI-TYPE-PDF--CAPS" role="constant">
 260 <term><literal>PANGO_BIDI_TYPE_PDF</literal></term>
 261 <listitem><simpara> Pop Directional Format
 262 </simpara></listitem>
 263 </varlistentry>
 264 <varlistentry id="PANGO-BIDI-TYPE-EN--CAPS" role="constant">
 265 <term><literal>PANGO_BIDI_TYPE_EN</literal></term>
 266 <listitem><simpara> European Number
 267 </simpara></listitem>
 268 </varlistentry>
 269 <varlistentry id="PANGO-BIDI-TYPE-ES--CAPS" role="constant">
 270 <term><literal>PANGO_BIDI_TYPE_ES</literal></term>
 271 <listitem><simpara> European Number Separator
 272 </simpara></listitem>
 273 </varlistentry>
 274 <varlistentry id="PANGO-BIDI-TYPE-ET--CAPS" role="constant">
 275 <term><literal>PANGO_BIDI_TYPE_ET</literal></term>
 276 <listitem><simpara> European Number Terminator
 277 </simpara></listitem>
 278 </varlistentry>
 279 <varlistentry id="PANGO-BIDI-TYPE-AN--CAPS" role="constant">
 280 <term><literal>PANGO_BIDI_TYPE_AN</literal></term>
 281 <listitem><simpara> Arabic Number
 282 </simpara></listitem>
 283 </varlistentry>
 284 <varlistentry id="PANGO-BIDI-TYPE-CS--CAPS" role="constant">
 285 <term><literal>PANGO_BIDI_TYPE_CS</literal></term>
 286 <listitem><simpara> Common Number Separator
 287 </simpara></listitem>
 288 </varlistentry>
 289 <varlistentry id="PANGO-BIDI-TYPE-NSM--CAPS" role="constant">
 290 <term><literal>PANGO_BIDI_TYPE_NSM</literal></term>
 291 <listitem><simpara> Nonspacing Mark
 292 </simpara></listitem>
 293 </varlistentry>
 294 <varlistentry id="PANGO-BIDI-TYPE-BN--CAPS" role="constant">
 295 <term><literal>PANGO_BIDI_TYPE_BN</literal></term>
 296 <listitem><simpara> Boundary Neutral
 297 </simpara></listitem>
 298 </varlistentry>
 299 <varlistentry id="PANGO-BIDI-TYPE-B--CAPS" role="constant">
 300 <term><literal>PANGO_BIDI_TYPE_B</literal></term>
 301 <listitem><simpara> Paragraph Separator
 302 </simpara></listitem>
 303 </varlistentry>
 304 <varlistentry id="PANGO-BIDI-TYPE-S--CAPS" role="constant">
 305 <term><literal>PANGO_BIDI_TYPE_S</literal></term>
 306 <listitem><simpara> Segment Separator
 307 </simpara></listitem>
 308 </varlistentry>
 309 <varlistentry id="PANGO-BIDI-TYPE-WS--CAPS" role="constant">
 310 <term><literal>PANGO_BIDI_TYPE_WS</literal></term>
 311 <listitem><simpara> Whitespace
 312 </simpara></listitem>
 313 </varlistentry>
 314 <varlistentry id="PANGO-BIDI-TYPE-ON--CAPS" role="constant">
 315 <term><literal>PANGO_BIDI_TYPE_ON</literal></term>
 316 <listitem><simpara> Other Neutrals
 317 </simpara></listitem>
 318 </varlistentry>
 319 </variablelist><para role="since">Since 1.22</para></refsect2>
 320 <refsect2 id="pango-bidi-type-for-unichar" role="function" condition="since:1.22">
 321 <title>pango_bidi_type_for_unichar ()</title>
 322 <indexterm zone="pango-bidi-type-for-unichar" role="1.22"><primary sortas="pango_bidi_type_for_unichar">pango_bidi_type_for_unichar</primary></indexterm><programlisting><link linkend="PangoBidiType">PangoBidiType</link>       pango_bidi_type_for_unichar         (<link linkend="gunichar">gunichar</link> ch);</programlisting>
 323 <para>
 324 Determines the normative bidirectional character type of a
 325 character, as specified in the Unicode Character Database.
 326 </para>
 327 <para>
 328 A simplified version of this function is available as
 329 <link linkend="pango-unichar-get-direction"><function>pango_unichar_get_direction()</function></link>.</para>
 330 <para>
 331 </para><variablelist role="params">
 332 <varlistentry><term><parameter>ch</parameter>&#160;:</term>
 333 <listitem><simpara> a Unicode character
 334 </simpara></listitem></varlistentry>
 335 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the bidirectional character type, as used in the
 336 Unicode bidirectional algorithm.
 337
 338 </simpara></listitem></varlistentry>
 339 </variablelist><para role="since">Since 1.22</para></refsect2>
 340
 341 </refsect1>
 342
 343
 344
 345 <refsect1 id="pango-Bidirectional-Text.see-also">
 346 <title>See Also</title>
 347 <para>
 348 <link linkend="pango-context-get-base-dir"><function>pango_context_get_base_dir()</function></link>,
 349 <link linkend="pango-context-set-base-dir"><function>pango_context_set_base_dir()</function></link>,
 350 <link linkend="pango-itemize-with-base-dir"><function>pango_itemize_with_base_dir()</function></link>
 351 </para>
 352 </refsect1>
 353
 354 </refentry>