Pango Reference Manual: Bidirectional Text

## Bidirectional Text Bidirectional Text — Types and functions to help with handling bidirectional text |

## Synopsis

    enum                PangoDirection;
    PangoDirection      pango_unichar_direction             (gunichar ch);
    PangoDirection      pango_find_base_dir                 (const gchar *text,
                                                             gint length);
    gboolean            pango_get_mirror_char               (gunichar ch,
                                                             gunichar *mirrored_ch);
    enum                PangoBidiType;
    PangoBidiType       pango_bidi_type_for_unichar         (gunichar ch);

## Object Hierarchy

      GEnum
       +----PangoDirection

      GEnum
       +----PangoBidiType

## Description

Pango supports bidirectional text (like Arabic and Hebrew) automatically. Some applications however, need some help to correctly handle bidirectional text.

The PangoDirection type can be used with `pango_context_set_base_dir()` to instruct Pango about direction of text, though in most cases Pango detects that correctly and automatically. The rest of the facilities in this section are used internally by Pango already, and are provided to help applications that need more direct control over bidirectional setting of text.

## Details

### enum PangoDirection

    typedef enum {
      PANGO_DIRECTION_LTR,
      PANGO_DIRECTION_RTL,
      PANGO_DIRECTION_TTB_LTR,
      PANGO_DIRECTION_TTB_RTL,
      PANGO_DIRECTION_WEAK_LTR,
      PANGO_DIRECTION_WEAK_RTL,
      PANGO_DIRECTION_NEUTRAL
    } PangoDirection;

The PangoDirection type represents a direction in the Unicode bidirectional algorithm; not every value in this enumeration makes sense for every usage of PangoDirection; for example, the return value of `pango_unichar_direction()` and `pango_find_base_dir()` cannot be `PANGO_DIRECTION_WEAK_LTR` or `PANGO_DIRECTION_WEAK_RTL`, since every character is either neutral or has a strong direction; on the other hand `PANGO_DIRECTION_NEUTRAL` doesn't make sense to pass to `pango_itemize_with_base_dir()`.

The `PANGO_DIRECTION_TTB_LTR`, `PANGO_DIRECTION_TTB_RTL` values come from an earlier interpretation of this enumeration as the writing direction of a block of text and are no longer used; See PangoGravity for how vertical text is handled in Pango.

`PANGO_DIRECTION_LTR` | A strong left-to-right direction
`PANGO_DIRECTION_RTL` | A strong right-to-left direction
`PANGO_DIRECTION_TTB_LTR` | Deprecated value; treated the same as `PANGO_DIRECTION_RTL`.
`PANGO_DIRECTION_TTB_RTL` | Deprecated value; treated the same as `PANGO_DIRECTION_LTR`
`PANGO_DIRECTION_WEAK_LTR` | A weak left-to-right direction
`PANGO_DIRECTION_WEAK_RTL` | A weak right-to-left direction
`PANGO_DIRECTION_NEUTRAL` | No direction specified

### pango_unichar_direction ()

    PangoDirection      pango_unichar_direction             (gunichar ch);

Determines the inherent direction of a character; either `PANGO_DIRECTION_LTR`, `PANGO_DIRECTION_RTL`, or `PANGO_DIRECTION_NEUTRAL`.

This function is useful to categorize characters into left-to-right letters, right-to-left letters, and everything else. If full Unicode bidirectional type of a character is needed, `pango_bidi_type_for_unichar()` can be used instead.

`ch` : | a Unicode character
Returns : | the direction of the character.

### pango_find_base_dir ()

    PangoDirection      pango_find_base_dir                 (const gchar *text,
                                                             gint length);

Searches a string the first character that has a strong direction, according to the Unicode bidirectional algorithm.

`text` : | the text to process
`length` : | length of `text` in bytes (may be -1 if `text` is nul-terminated)
Returns : | The direction corresponding to the first strong character. If no such character is found, then `PANGO_DIRECTION_NEUTRAL` is returned.

Since 1.4

### pango_get_mirror_char ()

    gboolean            pango_get_mirror_char               (gunichar ch,
                                                             gunichar *mirrored_ch);

### Warning

`pango_get_mirror_char` is deprecated and should not be used in newly-written code.

If `ch` has the Unicode mirrored property and there is another Unicode character that typically has a glyph that is the mirror image of `ch`'s glyph, puts that character in the address pointed to by `mirrored_ch`.

Use `g_unichar_get_mirror_char()` instead; the docs for that function provide full details.

`ch` : | a Unicode character
`mirrored_ch` : | location to store the mirrored character
Returns : | `TRUE` if `ch` has a mirrored character and `mirrored_ch` is filled in, `FALSE` otherwise

### enum PangoBidiType

    typedef enum {
      /* Strong types */
      PANGO_BIDI_TYPE_L,
      PANGO_BIDI_TYPE_LRE,
      PANGO_BIDI_TYPE_LRO,
      PANGO_BIDI_TYPE_R,
      PANGO_BIDI_TYPE_AL,
      PANGO_BIDI_TYPE_RLE,
      PANGO_BIDI_TYPE_RLO,

      /* Weak types */
      PANGO_BIDI_TYPE_PDF,
      PANGO_BIDI_TYPE_EN,
      PANGO_BIDI_TYPE_ES,
      PANGO_BIDI_TYPE_ET,
      PANGO_BIDI_TYPE_AN,
      PANGO_BIDI_TYPE_CS,
      PANGO_BIDI_TYPE_NSM,
      PANGO_BIDI_TYPE_BN,

      /* Neutral types */
      PANGO_BIDI_TYPE_B,
      PANGO_BIDI_TYPE_S,
      PANGO_BIDI_TYPE_WS,
      PANGO_BIDI_TYPE_ON
    } PangoBidiType;

The PangoBidiType type represents the bidirectional character type of a Unicode character as specified by the Unicode bidirectional algorithm.

`PANGO_BIDI_TYPE_L` | Left-to-Right
`PANGO_BIDI_TYPE_LRE` | Left-to-Right Embedding
`PANGO_BIDI_TYPE_LRO` | Left-to-Right Override
`PANGO_BIDI_TYPE_R` | Right-to-Left
`PANGO_BIDI_TYPE_AL` | Right-to-Left Arabic
`PANGO_BIDI_TYPE_RLE` | Right-to-Left Embedding
`PANGO_BIDI_TYPE_RLO` | Right-to-Left Override
`PANGO_BIDI_TYPE_PDF` | Pop Directional Format
`PANGO_BIDI_TYPE_EN` | European Number
`PANGO_BIDI_TYPE_ES` | European Number Separator
`PANGO_BIDI_TYPE_ET` | European Number Terminator
`PANGO_BIDI_TYPE_AN` | Arabic Number
`PANGO_BIDI_TYPE_CS` | Common Number Separator
`PANGO_BIDI_TYPE_NSM` | Nonspacing Mark
`PANGO_BIDI_TYPE_BN` | Boundary Neutral
`PANGO_BIDI_TYPE_B` | Paragraph Separator
`PANGO_BIDI_TYPE_S` | Segment Separator
`PANGO_BIDI_TYPE_WS` | Whitespace
`PANGO_BIDI_TYPE_ON` | Other Neutrals

Since 1.22

### pango_bidi_type_for_unichar ()

    PangoBidiType       pango_bidi_type_for_unichar         (gunichar ch);

Determines the normative bidirectional character type of a character, as specified in the Unicode Character Database.

A simplified version of this function is available as `pango_unichar_direction()`.

`ch` : | a Unicode character
Returns : | the bidirectional character type, as used in the Unicode bidirectional algorithm.

Since 1.22

## See Also

pango_context_get_base_dir(), `pango_context_set_base_dir()`, `pango_itemize_with_base_dir()`