rb-text-helpers: Rhythmbox Development Reference Manual

## rb-text-helpers rb-text-helpers — text direction (LTR/RTL) functions |

## Functions

gboolean | rb_text_direction_conflict ()
PangoDirection | rb_text_common_direction ()
char * | rb_text_cat ()

## Description

Provides some helper functions for constructing strings that may include both left-to-right and right-to-left text.

## Functions

### rb_text_direction_conflict ()

    gboolean
    rb_text_direction_conflict (PangoDirection dir1,
                                PangoDirection dir2);

Direction conflict here means the two directions are defined (non-neutral) and they are different.

#### Parameters

dir1 | direction A |
dir2 | direction B |

#### Returns

`TRUE` if the two directions conflict.

### rb_text_common_direction ()

    PangoDirection
    rb_text_common_direction (const char *first,
                              ...);

This functions checks the direction of all given strings and:

1. If all strings are direction neutral, returns `PANGO_DIRECTION_NEUTRAL`;

2. If all strings are either LTR or neutral, returns `PANGO_DIRECTION_LTR`;

3. If all strings are either RTL or neutral, returns `PANGO_DIRECTION_RTL`;

4. If at least one is RTL and one LTR, returns `PANGO_DIRECTION_NEUTRAL`.

Note: neutral (1) and mixed (4) are two very different situations, they share a return code here only because they're the same for our specific use.

#### Parameters

first | first string |
... | rest of strings, terminated with `NULL` |

#### Returns

common direction of all strings, as defined above.

### rb_text_cat ()

    char *
    rb_text_cat (PangoDirection base_dir,
                 ...);

This function concatenates strings to a single string, preserving each part's original direction (LTR or RTL) using unicode markup, as detailed here: http://unicode.org/reports/tr9/.

It is called like this:

s = rb_text_cat(base_dir, str1, format1, ..., strN, formatN, `NULL`)

Format is a printf format with exactly one %s. "%s" or "" will insert the string as is.

Any string that is empty ("") will be skipped, its format must still be passed.

A space is inserted between strings.

The algorithm:

1. Caller supplies the base direction of the result in base_dir.

2. Insert either LRM or RLM at the beginning of the string to set its base direction, according to base_dir.

3. Find the direction of each string using pango.

4. For strings that have the same direction as the base direction, just insert them in.

5. For strings that have the opposite direction than the base one, insert them surrounded with embedding codes RLE/LRE .. PDF.

#### Parameters

base_dir | direction of the result string. |
... | pairs of strings (content, format) terminated with `NULL`. |

#### Returns

a new string containing the result.